OpenAPI Documentation

You can find the OpenAPI specification with requests examples for the Licenses service in the html document.

openapi: 3.0.0
info:
  version: 'v.0.3.33'
  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.3.33

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

    config_accept_content_type:
      schema:
        type: string
        enum:
          - application/json
          - text/plain
      required: false
      description: The content type of the response body.
  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

    include_luna_services:
      in: query
      name: include_luna_services
      schema:
        type: integer
        enum: [0, 1]
        default: 0
      description: whether to perform healthchecks for dependent luna services.

    accept_config_handler:
      in: header
      name: Accept
      schema:
        type: string
        enum:
          - application/json
          - text/plain
        description: One of application/json, text/plain
      required: false
      description: acceptable type of receiving data
  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

    consumed_executions:
      type: integer
      minimum: 0
      description: consumed executions number

    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

    version_response:
      type: object
      properties:
        Version:
          allOf:
          - $ref: '#/components/schemas/version'
          - description: service version info.
      required: [Version]

    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
        faces_limit:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: |
                information about allowed faces database size:

                - feature availability

                - 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
        liveness_balance:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: information about allowed liveness executions.
          example:
            is_available: True
            value: 1000
        streams_limit:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: maximum number of streams.
          example:
            is_available: True
            value: 10
        iso:
          allOf:
            - $ref: '#/components/schemas/license_feature'
            - description: information about ISO feature availability.
          example:
            is_available: True
            value: 1
      required: [expiration_time, faces_limit, liveness]

    health_ok:
      description: successful healthcheck execution info
      type: object
      properties:
        execution_time:
          type: number
          example: 0.123
          description: request execution time in seconds
      required: [execution_time]

    health_errors:
      type: object
      properties:
        errors:
          description: failed healthcheck execution info
          type: array
          items:
            type: object
            properties:
              component:
                description: component name
                type: string
              error:
                allOf:
                  - description: healthcheck error
                  - $ref: '#/components/schemas/Error'
              status:
                description: component health status
                type: integer
                enum: [0, 1]
            required: [component, error, status]
      required: [errors]
      example:
        errors:
          - component: license
            error:
              error_code: 38001
              desc: Health check error
              detail: License error
            status: 0
          - component: luna_faces
            error:
              error_code: 0
              desc: Success
              detail: Success
            status: 1

    feature_execution_count:
      type: object
      properties:
        execution_count:
          type: integer
          minimum: 1
          description: execution count to consume for the feature
      required: [execution_count]

    consume_executions:
      type: object
      properties:
        liveness:
          allOf:
          - $ref: '#/components/schemas/feature_execution_count'
          description: |
            `liveness` feature
      required: [liveness]
      example:
        liveness:
          execution_count: 200

    executions_response:
      type: object
      properties:
        liveness:
          type: object
          properties:
            result:
              allOf:
              - $ref: '#/components/schemas/Error'
              description: |
                `liveness` executions consumption result
            consumed_executions:
              $ref: '#/components/schemas/consumed_executions'
          required: [result, consumed_executions]
          description: |
            `liveness` execution consumption result and consumed executions number
      required: [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_response'
        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'
  /1/license/executions:
    post:
      tags:
      - executions consumption

      summary: executions consumption
      description: Consume executions for the given features.
      operationId: consumeExecutions

      parameters:
      - $ref: '#/components/parameters/luna_request_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/consume_executions'
      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/executions_response'
              examples:
                success:
                  value:
                    liveness:
                      result:
                        error_code: 0
                        detail: Success
                        desc: Success
                      consumed_executions: 1
                not_found:
                  value:
                    liveness:
                      result:
                        error_code: 33004
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: NotFound"
                      consumed_executions: 0
                insufficient:
                  value:
                    liveness:
                      result:
                        error_code: 33005
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: license expired"
                      consumed_executions: 5
                expired:
                  value:
                    liveness:
                      result:
                        error_code: 33005
                        detail: License problem
                        desc: "Failed to consume PlatformLiveness: LicenseExpired"
                      consumed_executions: 0
        400:
          description: Bad request.
          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:
                bad_json:
                  value:
                    error_code: 12022
                    desc: Bad/incomplete input data
                    detail: 'Failed to validate input json. Path: '''',  message: ''Additional properties are not allowed (''userdata'' was unexpected)'''
        500:
          $ref: '#/components/responses/internal_server_license_error'
  /1/config:
    get:
      tags:
        - config
      summary: get service configuration
      description: Get service configuration. Passwords and tokens will be hidden in the response.
      operationId: getConfig

      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/accept_config_handler'
      responses:
        200:
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/config_accept_content_type'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                type: object
                description: json format configuration
              example:
                INFLUX_MONITORING:
                  SEND_DATA_FOR_MONITORING: 0
                  VERSION: 2
                  ORGANIZATION: ORGANIZATION_NAME
                  TOKEN: '********'
                  BUCKET: luna_monitoring
                  HOST: 127.0.0.1
                  PORT: 8086
                  USE_SSL: 0
                  FLUSHING_PERIOD: 1.0
            text/plain:
              schema:
                type: string
                description: text format configuration
              example: |
                [INFLUX_MONITORING]
                SEND_DATA_FOR_MONITORING = 0
                VERSION = 2
                ORGANIZATION = ORGANIZATION_NAME
                TOKEN = ********
                BUCKET = luna_monitoring
                HOST = 127.0.0.1
                PORT = 8086
                USE_SSL = 0
                FLUSHING_PERIOD = 1.0
        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'
  /healthcheck:
    get:
      tags:
        - health
      summary: get health
      description: get health of service
      operationId: healthcheck
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/include_luna_services'
      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/health_ok'
        500:
          $ref: '#/components/responses/internal_server_error'
        502:
          description: Unhealthy
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/health_errors'