OpenApi

View spec in html.

openapi: 3.0.0
info:
  version: 'v.0.0.5'
  title: 'luna-streams-retranslator API'
  description: |
     'VisionLabs luna-streams-retranslator'

components:
  headers:
    application_json:
      schema:
        type: string
        enum:
        - application/json
      required: true
      description: The content type of the response body.

    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

    docs_content_type:
      schema:
        type: string
        enum:
          - application/x-yaml
          - text/html
      required: true
      description: The content type of the response body.

    text_html:
      schema:
        type: string
        enum:
          - text/html
      required: true
      description: The content type of the response body.

    json_or_msgpack:
      schema:
        type: string
        enum:
        - application/json
        - application/msgpack
      required: true
      description: The content type of the response body.

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

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

    Accept:
      in: header
      name: Accept
      schema:
        type: string
        enum:
          - application/json
          - application/msgpack
      description: Preferred response content type

    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

    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.

    application_json_content:
      in: header
      name: Content-Type
      schema:
        type: string
        enum:
          - application/json
      description: Content type is application/json.

    luna_account_id_required:
      name: Luna-Account-Id
      in: header
      schema:
        type: string
        format: uuid
        example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a
        pattern: ^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89ab][a-f0-9]{3}-?[a-f0-9]{12}$
      description: Luna account Id. Designed to identify the created object.
      required: true

    account_id:
      in: query
      name: account_id
      schema:
        $ref: '#/components/schemas/uuid'
      description: Account ID.
      example: '8950722f-3fd4-4223-b48f-03f95f0e8dfb'

    restream_quality:
      in: query
      name: quality
      schema:
        $ref: '#/components/schemas/restream_quality'
      description: Restream quality filter.
      example: 720
      required: false

    restream_type:
      in: query
      name: type
      schema:
        $ref: '#/components/schemas/restream_type'
      description: Restream type.
      example: 'hls'
      required: false

    stream_id:
      in: path
      name: stream_id
      schema:
        $ref: '#/components/schemas/uuid'
      required: true
      description: Stream 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.
        link:
          type: string
          description: link to the documentation website with the error description.
      required: [error_code, detail, desc, link]
      example:
        error_code: 1
        detail: internal server error
        desc: internal server error
        link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-1"

    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:
        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 ]
      required: [ Version ]

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

    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: licenses
            error:
              error_code: 38001
              desc: Health check error
              detail: License error
              link: https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-38001
            status: 0

    restream_type:
      type: string
      enum: [ hls, rtsp ]

    restream_quality_base:
      type: integer
      multipleOf: 2
      minimum: 144
      maximum: 2160
      example: 720

    restream_quality:
      allOf:
        - $ref: '#/components/schemas/restream_quality_base'
      description: >
        Target restream quality. This parameter set the height of final stream resolution, the width will
        be calculated proportionally in accordance with the original stream resolution. The original stream quality
        will be used by default.

    restream_quality_reply:
      allOf:
        - $ref: '#/components/schemas/restream_quality_base'
      description: >
        This parameter means the height of stream resolution, the width calculated proportionally in accordance with 
        the original stream resolution.

    uuid:
      type: string
      format: uuid
      pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'
      example: "557d54ec-29ad-4f3c-93b4-c9092ef12515"

    stream_id:
      allOf:
        - $ref: '#/components/schemas/uuid'
        - description: source stream id

    stream_token:
      type: string
      description: jwt token for stream

    restream_url:
      type: string
      format: uri-reference
      description: restream url

    register_stream:
      type: object
      properties:
        url:
          type: string
          description: source stream url
      required: [ url ]

    stream_info:
      type: object
      properties:
        url:
          type: string
          description: Source stream url
        type:
          allOf:
            - $ref: '#/components/schemas/restream_type'
            - default: hls
        quality:
          $ref: '#/components/schemas/restream_quality'
      required: [ url ]

    restream_info_required:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/restream_url'
        type:
          $ref: '#/components/schemas/restream_type'
        quality:
          $ref: '#/components/schemas/restream_quality_reply'
        token:
          $ref: '#/components/schemas/stream_token'
      required: [ url, type, quality, token ]

    get_restreams_reply:
      type: array
      items:
        type: object
        properties:
          stream_id:
            $ref: '#/components/schemas/stream_id'
          url:
            type: string
            description: Restream url
          type:
            $ref: '#/components/schemas/restream_type'
          quality:
            $ref: '#/components/schemas/restream_quality_reply'
          token:
            $ref: '#/components/schemas/stream_token'
        required: [ stream_id, url, type, quality ]
  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'
paths:

  /1/streams/{stream_id}:
    parameters:
      - in: path
        name: stream_id
        schema:
          $ref: '#/components/schemas/uuid'
        required: true
    put:
      tags:
        - streams
      summary: register stream
      description: Register stream and start retranslation.
      operationId: registerStream
      parameters:
        - $ref: '#/components/parameters/luna_account_id_required'
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/application_json_content'
        - $ref: '#/components/parameters/stream_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/stream_info'
      responses:
        '200':
          description: Stream saved.
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restream_info_required'
        '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)'''
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022"
        '422':
          description: Unprocessable content.
          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: 46003
                    desc: Unprocessable Content
                    detail: 'The `` retranslation is not supported at the moment'
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022"
        '500':
          $ref: '#/components/responses/internal_server_error'

    get:
      tags:
        - streams
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/restream_quality'
        - $ref: '#/components/parameters/restream_type'
        - $ref: '#/components/parameters/stream_id'
      summary: get restreams
      description: Get restreams associated with stream.
      operationId: getRestreams
      responses:
        '200':
          description: Restream.
          headers:
            Content-Type:
              $ref: '#/components/headers/application_json'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_restreams_reply'
        '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)'''
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022"
        '404':
          description: Object not Found.
          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: 45002
                    desc: Object not found
                    detail: 'Stream with id 7acc35cf-a3b2-4f87-8d8b-5496a2782d37 not found'
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-45002"
        '500':
          $ref: '#/components/responses/internal_server_error'
    delete:
      tags:
        - streams
      parameters:
        - $ref: '#/components/parameters/luna_request_id'
        - $ref: '#/components/parameters/restream_quality'
        - $ref: '#/components/parameters/restream_type'
        - $ref: '#/components/parameters/stream_id'
      summary: delete restreams
      description: Delete restreams associated with stream.
      operationId: deleteResterams
      responses:
        '204':
          description: Deleted.
          headers:
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
        '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)'''
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12022"
        '404':
          description: Object not Found.
          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: 45002
                    desc: Object not found
                    detail: 'Stream with id 7acc35cf-a3b2-4f87-8d8b-5496a2782d37 not found'
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-45002"
        '500':
          $ref: '#/components/responses/internal_server_error'
  /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/json_or_msgpack'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/version'
            application/msgpack:
              schema:
                $ref: '#/components/schemas/version'
        500:
          $ref: '#/components/responses/internal_server_error'
  /1/docs/spec:
    get:
      tags:
        - documents
      summary: get openapi documentation
      description: |
        Get service OpenApi documentation. If *Accept* request header is of type `application/x-yaml`,
        returns documentation in `yaml` format or returns `html` documentation, if *Accept-Type* is `text/html`
      operationId: getSpec

      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
                description: yaml format documentation
            text/html:
              schema:
                type: string
                description: html format documentation
        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"
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12024"
        500:
          $ref: '#/components/responses/internal_server_error'
  /1/docs/dev:
    parameters:
      - $ref: '#/components/parameters/Accept'
    get:
      tags:
        - documents
      summary: get development manual
      description: |
        Get sphinx documentation - *Development Manual*. After the request you will be redirected to the page `/docs/dev/index.html`
      operationId: getDevManual

      parameters:
        - $ref: '#/components/parameters/luna_request_id'
      responses:
        200:
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/text_html'
            Luna-Request-Id:
              $ref: '#/components/headers/luna_request_id'
          content:
            text/html:
              schema:
                type: string
                description: html format documentation
        500:
          $ref: '#/components/responses/internal_server_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"
                    link: "https://docs.visionlabs.ai/info/luna/troubleshooting/errors-description/code-12024"
        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'