openapi: 3.0.0
info:
  version: 'v.0.1.32'
  title: 'Luna-Licenses'
  description: |
  
          VisionLabs Luna Licenses.

          OpenAPI specification is the only valid document providing up-to-date information about the service API. 

          The specification can be used:

          - By documentation generation tools to visualize the API.
          - By code generation tools.

          All the documents and code generated using this specification can include inaccuracies and should be carefully checked.

          OpenAPI specification can be received using the "/docs/spec" resource. The "Accept" header should be set to "application/x-yaml".

servers:
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/visionlabs/Luna3API/v.0.1.32

components:
  headers:
    application_json:
      schema:
        type: string
        enum:
        - application/json
      required: true
      description: content type is application/json

    text_plain:
      schema:
        type: string
        enum:
        - text/plain
      required: true
      description: content type is text/plain

    image_jpeg:
      schema:
        type: string
        enum:
        - image/jpeg
      description: content type is image/jpeg
      required: true

    luna_request_id:
      schema:
        type: string
        format: timestamp,uuid
        example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
        pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      description: request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
      required: true

    application_zip:
      schema:
        type: string
        enum:
        - application/zip
      required: true
      description: content type is application/zip

    docs_content_type:
      schema:
        type: string
        enum:
          - application/x-yaml
          - text/html
      required: true
      description: Type of recieving data

    content_disposition:
      schema:
        type: string
      example: 'attachment; filename=task_146.zip'
      required: true
      description: content disposition with filename
  parameters:
    page:
      in: query
      name: page
      schema:
        type: integer
        minimum: 1
        default: 1
      description: a page number.

    accept_docs_handler:
      in: header
      name: Accept
      schema:
        $ref: '#/components/schemas/accept_docs_handler'
      description: acceptable type of recieving data

    luna_request_id:
      in: header
      schema:
        type: string
        format: timestamp,uuid
        example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
        pattern: ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      description: |
        external request id. Helps to uniquely identify messages that correspond to particular requests, in system logs.
        If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.
      name: Luna-Request-Id
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: integer
          description: error code.
        desc:
          type: string
          description: short error description.
        detail:
          type: string
          description: error details.
      required:
      - error_code
      - detail
      - desc
      example:
        error_code: 1
        detail: internal server error
        desc: internal server error

    int_version:
      type: integer
      minimum: 0

    accept_docs_handler:
      type: string
      enum:
        - application/x-yaml
        - text/html
      description: One of application/x-yaml, text/html

    version:
      type: object
      properties:
        api:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: an api version of service.
        major:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: a major version of service.
        minor:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: a minor version of service.
        patch:
          allOf:
          - $ref: '#/components/schemas/int_version'
          - description: a patch version of service.
      required: [api, major, minor, patch]

      example:
        api: 1
        major: 0
        minor: 0
        patch: 0

    license_period:
      type: object
      properties:
        is_available:
          type: boolean
          description: whether the license is valid
          example: True
        value:
          type: string
          format: date-time
          description: license expiration time
          example: "2021-08-11T09:11:41.674Z"

    license_feature:
      type: object
      properties:
        is_available:
          type: boolean
          description: whether the license feature is available
          example: True
        value:
          type: integer
          nullable: True
          description: license feature current value

    license:
      type: object
      description: current license data
      properties:
        expiration_time:
          allOf:
            - $ref: '#/components/schemas/license_period'
            - description: expiration time of your license
        limit:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: | 
                information about allowed faces database size:

                - feature availability. When the limit is exceeded, the 'False' value is returned.

                - maximum number of faces with attached attributes
          example:
            is_available: True
            value: 1000
        liveness:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: information about liveness feature availability
          example:
            is_available: True
            value: 1
      required: [expiration_time, limit, liveness]
  responses:
    internal_server_error:
      description: internal server error.
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    internal_server_license_error:
      description: internal server error.
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            failed_to_check_feature:
              value:
                error_code: 33001
                desc: License problem
                detail: 'Failed to check HASP License feature HaspFeatureEnum.PlatformFacesLimit: HaspErrorEnum.Internal'
            failed_to_get_feature_value:
              value:
                error_code: 33002
                desc: License problem
                detail: 'Failed to get value of HASP License feature HaspFeatureEnum.PlatformFacesLimit: HaspErrorEnum.Internal'
            no_value_for_required_feature:
              value:
                error_code: 33003
                desc: License problem
                detail: 'No value found for required HASP License feature HaspFeatureEnum.PlatformFacesLimit: HaspErrorEnum.Internal'

    forbidden_error:
      description: forbidden, user did not set header Luna-Account-Id.
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: 11036
            desc: Forbidden
            detail: Luna-Account-Id header is required for requests that change the state of system
    forbidden_events_error:
      description: forbidden, luna-events support is disabled on server
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: 11040
            desc: Forbidden
            detail: Luna Events service is disabled
    forbidden_tasks_error:
      description: forbidden, luna-tasks support is disabled on server
      headers:
        Content-Type:
          $ref: '#/components/headers/application_json'
        Luna-Request-Id:
          $ref: '#/components/headers/luna_request_id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: 11039
            desc: Forbidden
            detail: Luna Tasks service is disabled
paths:
  /version:
    get:
      tags:
      - version

      summary: get version
      description: get service version
      operationId: getVersion

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      responses:
        200:
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/version'
        500:
          $ref: '#/components/responses/internal_server_error'
  /1/docs:
    get:
      tags:
      - documents

      summary: get docs
      description: get service documentation
      operationId: getDocs

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      - $ref: '#/components/parameters/accept_docs_handler'
      responses:
        200:
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/docs_content_type'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/x-yaml:
              schema:
                type: string
            text/html:
              schema:
                type: string
        415:
          description: Unsupported Media Type
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unsupported_media_type:
                  value:
                    error_code: 12024
                    detail: 'Bad/incomplete input data'
                    desc: "Unsupported media type"
        500:
          $ref: '#/components/responses/internal_server_error'
  /1/license:
    get:
      tags:
      - license

      summary: get license
      description: |
        Get license data:

        - license expiry date

        - the maximum allowed size of faces database

        - liveness feature availability

      operationId: getLicense

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      responses:
        200:
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/license'
        500:
          $ref: '#/components/responses/internal_server_license_error'