open-api.yaml

openapi: 3.1.0
info:
  title: iTop REST API Gateway
  version: 0.1.0
  contact:
    name: Vladimir Kunin
    url: https://github.com/knowitop/itop-krakend
servers:
  - url: http://localhost:8080
paths:
  /v1/{objectClass}:
    parameters:
      - $ref: '#/components/parameters/ObjectClassParameter'
    get:
      operationId: getObjectList
      summary: Get a list of objects of the class
      parameters:
        - $ref: '#/components/parameters/OutputFieldsParameter'
        - $ref: '#/components/parameters/LimitParameter'
        - $ref: '#/components/parameters/PageParameter'
        - $ref: '#/components/parameters/WhereParameter'
        - $ref: '#/components/parameters/FilterParameter'
      responses:
        "200":
          description: List of objects with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ObjectWithFieldsSchema'
                  code:
                    type: number
                    format: integer
                  message:
                    type: string
                    example: "Found: 11"
                  pagination:
                    type: object
                    properties:
                      count:
                        type: number
                        format: integer
                        description: Number of objects in the current response
                        example: 1
                      page:
                        type: number
                        format: integer
                        description: Current page number
                        example: 2
                      limit:
                        type: number
                        format: integer
                        description: Limit per page
                        example: 10
                      total:
                        type: number
                        format: integer
                        description: Total objects
                        example: 11
        "400":
          $ref: '#/components/responses/Error400'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
    post:
      operationId: createObject
      summary: Create a new object of the class
      parameters:
        - $ref: '#/components/parameters/OutputFieldsParameter'
        - $ref: '#/components/parameters/ApiCommentParameter'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Object fields with values to create a new object
            examples:
              extKey:
                $ref: '#/components/examples/ExtKeyFieldsExample'
      responses:
        "201":
          description: Created object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithFieldsSchema'
        "400":
          $ref: '#/components/responses/Error400'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
  /v1/{objectClass}/{objectId}:
    parameters:
      - $ref: '#/components/parameters/ObjectClassParameter'
      - $ref: '#/components/parameters/ObjectIdParameter'
      - $ref: '#/components/parameters/OutputFieldsParameter'
    get:
      operationId: getObject
      summary: Get an object
      responses:
        "200":
          description: Requested object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithFieldsSchema'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: "#/components/responses/Error502"
        default:
          $ref: '#/components/responses/ErrorDefault'
    put:
      operationId: updateObject
      summary: Update an object
      parameters:
        - $ref: '#/components/parameters/ApiCommentParameter'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Object fields with values to update
              example: { "title": "New desktop for Paul", "service_id": 12, "servicesubcategory_id": 45 }
      responses:
        "200":
          description: Updated object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithFieldsSchema'
        "400":
          $ref: '#/components/responses/Error400'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
    delete:
      operationId: deleteObject
      summary: Delete an object
      description: Delete an object and its associated dependent objects that are available for auto-deletion
      parameters:
        - $ref: '#/components/parameters/ApiCommentParameter'
        - $ref: '#/components/parameters/SimulateParameter'
      responses:
        "200":
          description: Deleted and updated objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  objects:
                    type: array
                    items:
                      $ref: '#/components/schemas/ObjectWithFieldsSchema'
                  code:
                    type: number
                    format: integer
                  message:
                    type: string
                    example: "SIMULATING: Deleted: 1 plus (for DB integrity) 5"
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
  /v1/{objectClass}/{objectId}/comments/{caseLog}:
    parameters:
      - $ref: '#/components/parameters/ObjectClassParameter'
      - $ref: '#/components/parameters/ObjectIdParameter'
      - $ref: '#/components/parameters/CaseLogParameter'
    get:
      operationId: getObjectCaseLogEntries
      summary: Get object case log entries
      responses:
        "200":
          description: Requested case log content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithCaseLogSchema'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
    post:
      operationId: addObjectCaseLogEntry
      summary: Add a new case log entry
      parameters:
        - $ref: '#/components/parameters/ApiCommentParameter'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseLogSchema'
      responses:
        "200":
          description: Updated case log content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithCaseLogSchema'
        "400":
          $ref: '#/components/responses/Error400'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
  /v1/{objectClass}/{objectId}/stimulus/{stimulus}:
    parameters:
      - $ref: '#/components/parameters/ObjectClassParameter'
      - $ref: '#/components/parameters/ObjectIdParameter'
      - $ref: '#/components/parameters/StimulusParameter'
      - $ref: '#/components/parameters/OutputFieldsParameter'
      - $ref: '#/components/parameters/ApiCommentParameter'
    post:
      operationId: applyObjectStimulus
      summary: Apply a stimulus to the specified object
      description: Apply lifecycle transitions (aka 'stimulus', like 'assign', 'resolve', etc.) to objects with an existing lifecycle.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Object fields with values to be updated during the transition
              example: { "team_id": 10, "agent_id": 34 }
      responses:
        "200":
          description: Updated object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithFieldsSchema'
        "400":
          $ref: '#/components/responses/Error400'
        "401":
          $ref: '#/components/responses/Error401'
        "403":
          $ref: '#/components/responses/Error403'
        "404":
          $ref: '#/components/responses/Error404'
        "422":
          $ref: '#/components/responses/Error422'
        "500":
          $ref: '#/components/responses/Error500'
        "502":
          $ref: '#/components/responses/Error502'
        default:
          $ref: '#/components/responses/ErrorDefault'
components:
  parameters:
    ObjectClassParameter:
      name: objectClass
      in: path
      required: true
      description: Object class
      schema:
        type: string
        example: UserRequest
    ObjectIdParameter:
      name: objectId
      in: path
      required: true
      description: Object ID
      schema:
        type: number
        example: 45
    CaseLogParameter:
      name: caseLog
      in: path
      required: true
      description: Case log attribute name
      schema:
        type: string
        example: public_log
    StimulusParameter:
      name: stimulus
      in: path
      required: true
      description: Stimulus name
      schema:
        type: string
        example: ev_assign, ev_resolve
    OutputFieldsParameter:
      name: output_fields
      description: Mapped to the `output_fields` property in standard json_data.
      in: query
      required: false
      schema:
        type: string
        default: id,friendlyname
        example: ref,title,caller_id_friendlyname
    LimitParameter:
      name: limit
      description: Mapped to the `limit` property in standard json_data.
      in: query
      required: false
      schema:
        type: number
        format: int
        default: 100
    PageParameter:
      name: page
      description: Mapped to the `page` property in standard json_data.
      in: query
      required: false
      schema:
        type: number
        format: int
        default: 1
    WhereParameter:
      name: where
      description: OQL search condition, mapped to the `key` property in standard json_data. Ignored when using `filter` parameter.
      in: query
      required: false
      schema:
        type: string
        example: agent_id = 34 AND start_date > CURRENT_DATE()
    FilterParameter:
      name: filter
      description: Full OQL search query, mapped to the `key` property in standard json_data.
      in: query
      required: false
      schema:
        type: string
        example: SELECT UserRequest AS ur WHERE ur.agent_id = 34 AND ur.start_date > CURRENT_DATE()
    ApiCommentParameter:
      name: api_comment
      description: Mapped to the `comment` property in standard json_data. This overrides the value of the `ITOP_API_COMMENT` environment variable.
      in: query
      required: false
      schema:
        type: string
        default: iTop REST API Gateway
    SimulateParameter:
      name: simulate
      description: Mapped to the `simulate` property in standard json_data.
      in: query
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    ObjectBaseSchema:
      type: object
      properties:
        code:
          type: number
          format: integer
        message:
          type: string
          description: "Standard iTop API message for the object (created, updated, Reset external keys: Agent, etc.)"
          example: ""
        class:
          type: string
          description: Object class
          example: UserRequest
        key:
          type: number
          format: integer
          description: Object ID
          example: 45
    ObjectWithFieldsSchema:
      allOf:
        - $ref: '#/components/schemas/ObjectBaseSchema'
        - type: object
          properties:
            fields:
              type: object
              description: Object fields specified by `output_fields` parameter
              example: { "ref": "R-000045", "title": "New desktop for Paul", "caller_id_friendlyname": "Paul McCartney" }
    ObjectWithCaseLogSchema:
      allOf:
        - $ref: '#/components/schemas/ObjectBaseSchema'
        - type: object
          properties:
            case_log:
              type: string
              description: Case log name
              example: public_log
            entries:
              type: array
              description: Case log entries
              items:
                $ref: '#/components/schemas/CaseLogSchema'
              example: [
                {
                  "date": "2022-12-11 14:21:04",
                  "user_login": "martina",
                  "user_id": "20",
                  "message": "Help!",
                  "message_html": "<p>Help!</p>"
                },
                {
                  "date": "2022-12-11 14:27:35",
                  "user_login": "admin",
                  "user_id": "1",
                  "message": "From backend with love!",
                  "message_html": "<p>From backend with love!</p>"
                }
              ]
    CaseLogSchema:
      type: object
      properties:
        date:
          type: string
          description: Date and time in the format `YYYY-MM-DD hh:mm:ss` (current date by default)
          format: date-time
          example: 2022-12-11 14:21:04
        user_login:
          type: string
          example: martina
          readOnly: true
        user_id:
          type: string
          description: Entry author user ID (by default, the credentials used for the request), can only be set by users with the `Administrator` profile
          example: "20"
        message:
          type: string
          example: Hello REST API
        message_html:
          type: string
          example: <p>Hello REST API</p>
          readOnly: true
        format:
          type: string
          enum:
            - text
            - html
          default: text
          writeOnly: true
      required:
        - message
    ErrorSchema:
      type: object
      properties:
        code:
          type: number
          format: integer
          description: "Error code from standard response (see [docs](https://www.itophub.io/wiki/page?id=latest%3Aadvancedtopics%3Arest_json#error_codes))"
          example: 100
        message:
          type: string
          example: "Error: output_fields: invalid attribute code 'status'"
      required: [ message ]
  responses:
    Error400:
      description: |-
        **Bad Request** – invalid request parameters or body.
        
        Includes next codes from standard response:
        - 13 INVALID_PAGE The request page number is not valid. It must be an integer greater than 0
    Error401:
      description: |-
        **Unauthorized** – user authentication failed.
        
        When this occurs, iTop sends `text/html` page instead of `application/json` in response to a request with incorrect credentials. A part of the original response body will be included in the `message` for debugging, and the `code` will be missing.
    Error403:
      description: |-
        **Forbidden** – user does not have enough rights to perform the request.
        
        Includes next codes from standard response:
          - 1 UNAUTHORIZED Missing/wrong credentials or the user does not have enough rights to perform the requested operation
    Error404:
      description: |-
        **Not Found** – requested URL is invalid or object with the ID not exist.
    Error422:
      description: |-
        **Unprocessable Entity** – the request is syntactically correct, but for some reason cannot be processed.
        
        Includes next codes from standard response:
        - 12 UNSAFE The requested operation cannot be performed because it can cause data (integrity) loss
        - 100 INTERNAL_ERROR The operation could not be performed, see the message for troubleshooting
        
          Code 100 with next messages:
          - `Error: {att_code}: No item found with criteria ...` – When trying to set a non-existent object as a property value using JSON
          - `Error: {att_code}: Invalid object ...` – When trying to set a non-existent object as a property value using Id
          - `Missing mandatory attribute(s) for applying the stimulus ...`
          - `Invalid stimulus: '{stimulus}' on the object ...`
          - `Error: Found issue(s): target_class = {class}, target_id = {id} ...` – When deletion plan required manual operations
    Error500:
      description: |-
        **Internal Server Error** – iTop internal error or errors in the gateway's area of responsibility.
        
        Includes next codes from standard response:
        - 2 MISSING_VERSION The parameter 'version' is missing
        - 3 MISSING_JSON The parameter 'json_data' is missing
        - 4 INVALID_JSON The input structure is not a valid JSON string
        - 5 MISSING_AUTH_USER The parameter 'auth_user' is missing
        - 6 MISSING_AUTH_PWD The parameter 'auth_pwd' is missing or you are using url login type and it's not allowed on the Configuration file of your iTop
        - 10 UNSUPPORTED_VERSION No operation is available for the specified version
        - 11 UNKNOWN_OPERATION The requested operation is not valid for the specified version
    Error502:
      description: |-
        **Bad Gateway** – invalid response from the iTop API.
        
        It occurs when iTop responds with `text/html` instead of `application/json` for some reason. A small part of the original response body will be included in the `message` for debugging, and the `code` will be missing.
    ErrorDefault:
      description: |-
        **Internal Error** – unexpected error.
        
        Includes next codes from standard response:
        - 100 INTERNAL_ERROR The operation could not be performed, see the message for troubleshooting
        
        **NOTE:** the standard API sends a response with this code for many client errors (for example, an incorrect field in `output_fields`, etc.).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorSchema'
  examples:
    ExtKeyFieldsExample:
      summary: External key fields example
      description: Specify external key fields as a number, a nested object or an OQL query
      value: {
        "org_id": 10,
        "caller_id": {
          "email": "johndoe@acme.corp",
          "status": "active",
          "org_id": "10"
        },
        "service_id": "SELECT Service WHERE name = 'Office Support'",
        "title": "New user request",
        "description": "Request description"
      }
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP authentication, the iTop configuration parameter `allowed_login_types` must include the value `basic`.
security:
  - basicAuth: []