openapi: 3.1.0
info:
  title: Proxy API
  description: REST API for managing Proxies in the platform
  contact:
    name: ILM
    url: https://www.otilm.com
    email: ilm@omnitrust.com
  license:
    name: "Apache License, Version 2.0"
    url: https://github.com/OmniTrustILM/interface-documentation/blob/main/LICENSE.md
  version: 2.20.0
  x-logo:
    url: images/ilm-logo.svg
externalDocs:
  description: ILM Documentation
  url: https://docs.otilm.com
servers:
- url: https://demo.otilm.com/api
  description: ILM Demo server
tags:
- name: Proxy Management
  description: Proxy Management API
paths:
  /v1/proxies/{uuid}:
    get:
      tags:
      - Proxy Management
      summary: Get details of a Proxy
      operationId: getProxy
      parameters:
      - name: uuid
        in: path
        description: Proxy UUID
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Proxy details retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProxyDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
    put:
      tags:
      - Proxy Management
      summary: Edit a Proxy
      operationId: editProxy
      parameters:
      - name: uuid
        in: path
        description: Proxy UUID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProxyUpdateRequestDto"
        required: true
      responses:
        "200":
          description: Proxy updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProxyDto"
        "422":
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
    delete:
      tags:
      - Proxy Management
      summary: Delete a Proxy
      operationId: deleteProxy
      parameters:
      - name: uuid
        in: path
        description: Proxy UUID
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Proxy deleted
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/proxies:
    get:
      tags:
      - Proxy Management
      summary: List Proxies by Status
      operationId: listProxies
      parameters:
      - name: status
        in: query
        required: false
        schema:
          $ref: "#/components/schemas/ProxyStatus"
      responses:
        "200":
          description: List all Proxies
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProxyListDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
    post:
      tags:
      - Proxy Management
      summary: Create a new Proxy
      operationId: createProxy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProxyRequestDto"
        required: true
      responses:
        "201":
          description: New Proxy created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UuidDto"
        "422":
          description: Unprocessable Content
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - Error Message 1
              - Error Message 2
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
  /v1/proxies/{uuid}/instructions:
    get:
      tags:
      - Proxy Management
      summary: Get instructions to install a Proxy
      operationId: getInstallationInstructions
      parameters:
      - name: uuid
        in: path
        description: Proxy UUID
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Proxy installation instructions retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProxyInstallInstructionsDto"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationServiceExceptionDto"
        "500":
          description: Internal Server Error
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
      security:
      - SessionAuth: []
      - CertificateAuth: []
      - BearerJWTAuth: []
components:
  schemas:
    ProxyUpdateRequestDto:
      type: object
      properties:
        description:
          type: string
          description: Detailed description of the Proxy
          examples:
          - This proxy is used for connecting to external connectors in DMZ network
    ErrorMessageDto:
      type: object
      properties:
        message:
          type: string
          description: Error message detail
          examples:
          - Error message
      required:
      - message
    AuthenticationServiceExceptionDto:
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
          description: Status code of the HTTP Request
        code:
          type: string
          description: Code of the result
        message:
          type: string
          description: Exception message
      required:
      - code
      - message
      - statusCode
    ConnectorStatus:
      type: string
      enum:
      - waitingForApproval
      - connected
      - failed
      - offline
    ConnectorSummaryDto:
      type: object
      properties:
        uuid:
          type: string
          description: Object identifier
          examples:
          - 7b55ge1c-844f-11dc-a8a3-0242ac120002
        name:
          type: string
          description: Object Name
          examples:
          - Name
        url:
          type: string
          description: URL of the Connector
          examples:
          - http://network-discovery-provider:8080
        status:
          $ref: "#/components/schemas/ConnectorStatus"
          description: Status of the Connector
          examples:
          - CONNECTED
      required:
      - name
      - status
      - url
      - uuid
    ProxyDto:
      type: object
      properties:
        uuid:
          type: string
          description: Object identifier
          examples:
          - 7b55ge1c-844f-11dc-a8a3-0242ac120002
        name:
          type: string
          description: Object Name
          examples:
          - Name
        description:
          type: string
          description: Detailed description of the Proxy
          examples:
          - This proxy is used for connecting to external connectors in DMZ network
        code:
          type: string
          description: Code of the Proxy
          examples:
          - my-proxy-123
        status:
          $ref: "#/components/schemas/ProxyStatus"
          description: Status of the Proxy
          examples:
          - connected
        lastActivity:
          type: string
          format: date-time
          description: Timestamp of the last activity from the Proxy
          examples:
          - 2024-01-15T10:15:30+01:00
        connectors:
          type: array
          description: List of Connectors associated with the Proxy
          items:
            $ref: "#/components/schemas/ConnectorSummaryDto"
      required:
      - code
      - name
      - status
      - uuid
    ProxyStatus:
      type: string
      enum:
      - initialized
      - provisioning
      - failed
      - waitingForInstallation
      - connected
      - disconnected
    ProxyRequestDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the Proxy
          examples:
          - MyProxy123
        description:
          type: string
          description: Detailed description of the Proxy
          examples:
          - This proxy is used for connecting to external connectors in DMZ network
      required:
      - name
    UuidDto:
      type: object
      properties:
        uuid:
          type: string
          description: Object identifier
      required:
      - uuid
    ProxyListDto:
      type: object
      properties:
        uuid:
          type: string
          description: Object identifier
          examples:
          - 7b55ge1c-844f-11dc-a8a3-0242ac120002
        name:
          type: string
          description: Object Name
          examples:
          - Name
        description:
          type: string
          description: Detailed description of the Proxy
          examples:
          - This proxy is used for connecting to external connectors in DMZ network
        status:
          $ref: "#/components/schemas/ProxyStatus"
          description: Status of the Proxy
          examples:
          - connected
        lastActivity:
          type: string
          format: date-time
          description: Timestamp of the last activity from the Proxy
          examples:
          - 2024-01-15T10:15:30+01:00
      required:
      - name
      - status
      - uuid
    ProxyInstallInstructionsDto:
      type: object
      properties:
        uuid:
          type: string
          description: Proxy identifier
          examples:
          - 7b55be1c-844f-11dc-a8a3-0242ac120002
        installationInstructions:
          type: string
          description: Installation instructions for the Proxy
          examples:
          - helm install my-proxy ./proxy --set proxy.code=my-proxy-123
      required:
      - uuid
  securitySchemes:
    SessionAuth:
      type: apiKey
      description: Session-based authentication with session ID stored in 'session-id'
        cookie
      name: session-id
      in: cookie
    CertificateAuth:
      type: apiKey
      description: Base64 encoded X.509 certificate passed in header
      name: ssl-client-cert
      in: header
    BearerJWTAuth:
      type: http
      scheme: Bearer
      bearerFormat: JWT