openapi: 3.0.0
info:
  title: VDX Pexip History Service
  description: API description for VDX Pexip History Service
  version: 1.11.0
  contact:
    email: development@kvalitetitsit.dk
tags:
  - name: Info
    description: Technical information regarding the service
  - name: live-status
    description: Live conference information. Endpoints is secured with an API key.
  - name: historic
    description: Historic conference information. Endpoints is secured with an API key.
  - name: live-status-idws
    description: Live conference information. Endpoints is secured with OIO IDWSREST.
  - name: historic-idws
    description: Historic conference information. Endpoints is secured with OIO IDWSREST.
servers:
  - url: '{protocol}://{environment}:{port}'
    variables:
      protocol:
        enum:
          - http
          - https
        default: http
      environment:
        enum:
          - localhost # Docker-compose setup
        default: localhost # Development
      port:
        enum:
          - '8080'
        default: '8080'
paths:
  /apikey/status/v1/conference/{uri_with_domain}:
    get:
      tags:
        - live-status
      security:
        - apiKeyAuth: []
      summary: Get a specific status
      description: Get a specific status identified by uri with domain.
      parameters:
        - name: uri_with_domain
          in: path
          required: true
          schema:
            type: string
          example: '123@some.domain'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /apikey/status/v1/conference/list/{group_id}:
    get:
      tags:
        - live-status
      security:
        - apiKeyAuth: []
      summary: Get status by group id.
      description: Get a list of status identified by group id.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /apikey/status/v1/conference/list:
    get:
      tags:
        - live-status
      security:
        - apiKeyAuth: []
      summary: Get status.
      description: Get a list of status.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /apikey/history/v1/conference:
    get:
      tags:
        - historic
      security:
        - apiKeyAuth: []
      summary: Get historic conferences
      description: Get all historic conferences for the organisation hierarchy that the API key grants access to.
      parameters:
        - in: query
          name: start_time__gte
          required: true
          schema:
            type: string
            format: date-time
        - in: query
          name: end_time__lt
          required: false
          schema:
            type: string
            format: date-time
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/historic-conference'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '501':
          $ref: '#/components/responses/501'
  /apikey/history/v1/conference/{conference_id}:
    get:
      tags:
        - historic
      summary: Get historic conferences by ID
      description: Get historicconferences by ID
      parameters:
        - name: conference_id
          in: path
          required: true
          schema:
            type: string
          example: 8583f400-7886-48c9-874b-5fefc2ac097e
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/historic-conference'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '501':
          $ref: '#/components/responses/501'
  /idws/status/v1/conference/{uri_with_domain}:
    get:
      tags:
        - live-status-idws
      summary: Get a specific status
      description: Get a specific status identified by uri with domain.
      parameters:
        - name: uri_with_domain
          in: path
          required: true
          schema:
            type: string
          example: '123@some.domain'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /idws/status/v1/conference/list/{group_id}:
    get:
      tags:
        - live-status-idws
      summary: Get status by group id.
      description: Get a list of status identified by group id.
      parameters:
        - name: group_id
          in: path
          required: true
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /idws/status/v1/conference/list:
    get:
      tags:
        - live-status-idws
      summary: Get status.
      description: Get a list of status.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/live-conference'
        '404':
          $ref: '#/components/responses/404'
  /idws/history/v1/conference:
    get:
      tags:
        - historic-idws
      summary: Get historic conferences
      description: Get all historic conferences for the organisation hierarchy that the API key grants access to.
      parameters:
        - in: query
          name: start_time__gte
          required: true
          schema:
            type: string
            format: date-time
        - in: query
          name: end_time__lt
          required: false
          schema:
            type: string
            format: date-time
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/historic-conference'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '501':
          $ref: '#/components/responses/501'
  /idws/history/v1/conference/{conference_id}:
    get:
      tags:
        - historic-idws
      summary: Get historic conferences by ID
      description: Get historicconferences by ID
      parameters:
        - name: conference_id
          in: path
          required: true
          schema:
            type: string
          example: 8583f400-7886-48c9-874b-5fefc2ac097e
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/historic-conference'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '501':
          $ref: '#/components/responses/501'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  responses:
    '400':
      description: "Bad Request. This could be because: * One of the required parameters/properties are missing or is empty <br> * Length of input is exceeding maximum length <br> (See a possible detailed error message in the in the response.)"
    '401':
      description: "Unauthorized. This could be because: <br> * The calling system has not been properly authenticated."
    '403':
      description: "Forbidden. This could be because: <br> * The requested information does not belong the organisation of the user <br> * The calling user does not have the required roles"
    '404':
      description: "Not Found. This could be because: <br> * The participant requested has been deleted or has never existed"
    '501':
      description: "Not Implemented. This could be because: * The combination of parameters is not supported <br> * See a possible detailed error message in the in the response"
  schemas:
    additional_info_type:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: key of additional info field
          example: key
        value:
          type: string
          description: value of additional info field
          example: value
    conference:
      type: object
      properties:
        duration:
          type: integer
          format: int32
          example: 579
          default: 0
          description: The duration of the conference in seconds
        instant_message_count:
          type: integer
          format: int32
          example: 0
          default: 0
          description: The number of instant messages sent in the conference
        start_time:
          type: string
          format: date-time
          example: 2020-05-21T17:32:28.556929
          description: The time at which the conference started
        end_time:
          type: string
          format: date-time
          example: 2020-04-21T17:32:28.556929
          default: null
          description: The time at which the conference ended
        service_type:
          type: string
          example: conference
          description: The type of conferencing service
        participant_count:
          type: integer
          format: int32
          example: 2
          description: The number of participants that joined the conference
        resource_uri:
          type: string
          example: /history/v1/conference/8583f400-7886-48c9-874b-5fefc2ac097e/
          description: The URI that identifies this resource
        name:
          type: string
          example: meet.alice
          description: The name used to refer to the service. Maximum length 250 characters
          maxLength: 250
        id:
          type: string
          example: 8583f400-7886-48c9-874b-5fefc2ac097e
          uniqueItems: true
          description: The primary key
        tag:
          type: string
          example: tag
          description: The unique identifier used to track usage of the service. Maximum length 250 characters
          maxLength: 250
        participants:
          type: array
          items:
            type: string
            example: [/history/v1/participant/e9883f1d-88ca-495d-8366-b6eb772dfe57/, /history/v1/participant/5881adda-00ef-4315-8886-5d873d2ef269/]
          description: The participants that joined the conference
    historic-conference:
      type: object
      required:
        - start_time
      properties:
        group_id:
          type: integer
          format: int32
        group_name:
          type: string
        conferenceId:
          type: string
          format: uuid
        name:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        duration:
          type: integer
          format: int32
        participant_count:
          type: integer
          format: int32
        overall_quality:
          type: string
        overall_quality_percent:
          type: number
          format: double
        local_alias:
          type: string
        remote_alias:
          type: string
        service_type:
          type: string
        meetingid:
          type: string
          format: uuid
        meeting_start_time:
          type: string
          format: date-time
        meeting_end_time:
          type: string
          format: date-time
        meeting_uri_with_domain:
          type: string
        meeting_created_by_name:
          type: string
        meeting_organized_by_name:
          type: string
        meeting_project_code:
          type: string
        meeting_external_id:
          type: string
        additional_info:
          type: array
          items:
            $ref: '#/components/schemas/additional_info_type'
    #        participants:
    #          type: array
    #          items:
    #            $ref: '#/components/schemas/participant-ended'

    live-conference:
      type: object
      required:
        - start_time
      properties:
        id:
          type: string
        group_id:
          type: integer
          format: int32
        group_name:
          type: string
        organisation_name:
          type: string
        is_locked:
          type: boolean
        is_started:
          type: boolean
        name:
          type: string
        overall_quality:
          type: string
        overall_quality_percent:
          type: number
          format: double
        overall_quality_count:
          type: array
          items:
            type: integer
            format: int32
        is_encrypted:
          type: boolean
        service_type:
          type: string
        start_time:
          type: string
          #          format: date-time
          description: Date time without any offset information.
        aliases:
          type: array
          items:
            type: string
        participant_count:
          type: integer
          format: int32
        participants_data:
          type: array
          items:
            $ref: '#/components/schemas/live-participant'
    live-participant:
      type: object
      properties:
        bandwidth:
          type: integer
          format: int32
        bucketed_call_quality:
          type: array
          items:
            type: integer
            format: int32
        call_direction:
          type: string
        call_quality:
          type: string
        call_uuid:
          type: string
        conference:
          type: string
        connect_time:
          type: string
          #          format: date-time
          description: Date time without any offset information.
        conversation_id:
          type: string
        destination_alias:
          type: string
        display_name:
          type: string
        encryption:
          type: string
        has_media:
          type: boolean
        id:
          type: string
        is_muted:
          type: boolean
        is_presenting:
          type: boolean
        is_streaming:
          type: boolean
        license_count:
          type: integer
          format: int32
        license_type:
          type: string
        media_node:
          type: string
        participant_alias:
          type: string
        protocol:
          type: string
        proxy_node:
          type: string
        remote_address:
          type: string
        role:
          type: string
        rx_bandwidth:
          type: integer
          format: int32
        service_type:
          type: string
        signalling_node:
          type: string
        source_alias:
          type: string
        system_location:
          type: string
        tx_bandwidth:
          type: integer
          format: int32
        vendor:
          type: string
        media_streams:
          type: array
          items:
            $ref: '#/components/schemas/live-media-stream'
    live-media-stream:
      type: object
      properties:
        id:
          type: string
        node:
          type: string
        rx_bitrate:
          type: integer
          format: int32
        rx_codec:
          type: string
        rx_fps:
          type: number
          format: double
        rx_jitter:
          type: number
          format: double
        rx_packets_lost:
          type: number
          format: double
        rx_resolution:
          type: string
        rx_windowed_packet_lost:
          type: number
          format: double
        start_time:
          type: string
          description: Date time without any offset information.
        #          format: date-time
        tx_codec:
          type: string
        tx_fps:
          type: number
          format: double
        tx_jitter:
          type: number
          format: double
        tx_packet_loss:
          type: integer
          format: int32
        tx_packets_sent:
          type: integer
          format: int32
        tx_windows_packet_loss:
          type: number
          format: double
        type:
          type: string
    info:
      type: object
      properties:
        git:
          properties:
            commit:
              properties:
                time:
                  type: string
                  example: "10.10.2018 @ 11:52:54 CEST"
                id:
                  type: string
                  example: "97fd935"
                branch:
                  type: string
                  example: "master"
    health:
      type: object
      properties:
        status:
          type: string
          example: "UP"
        compoents:
          properties:
            diskSpace:
              properties:
                status:
                  type: string
                  example: "UP"
            mongo:
              properties:
                status:
                  type: string
                  example: "UP"
                details:
                  properties:
                    version:
                      type: string
                      example: "4.2.6"
            nats:
              properties:
                status:
                  type: string
                  example: "UP"
                details:
                  properties:
                    url:
                      type: string
                      example: "nats://localhost:4222"
                    status:
                      type: string
                      example: "CONNECTED"
    detailedError:
      allOf:
        - $ref: '#/components/schemas/basicError'
        - type: object
          required:
            - detailed_error
            - detailed_error_code
          properties:
            detailed_error:
              description: Detailed error text. This could be a text describing an validation error.
              type: string
            detailed_error_code:
              description:
              type: string
              enum:
                - 10
                - 20
    basicError:
      type: object
      required:
        - timestamp
        - status
        - error
        - path
      properties:
        error:
          description: Error message.
          type: string
        path:
          description: Path
          type: string
        status:
          description: HTTP status code
          type: integer
        timestamp:
          description: Time of error
          type: string
          format: date-time