openapi: 3.0.3
servers:
  - url: api/stats
info:
  description: |-
    API used to publish stats from a Flexisip server.
  version: 1.0.0
  title: Flexiapi Flexisip stats
  license:
    name: GNU GPL
    url: 'https://www.gnu.org/licenses/licenses.en.html'
tags:
  - name: messages
    description: Everything about messages
  - name: calls
    description: Everything about calls
  - name: conferences
    description: Everything about conferences
paths:

  #####################################################################################
  ############################# message ###############################################
  #####################################################################################
  /messages:
    post:
      tags:
        - messages
      summary: Add information about a new message
      description: Add information about a new message
      operationId: addMessage
      responses:
        '200':
          description: Successful operation
        '422':
          description: Invalid input
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
  /messages/{message_id}/to/{sip_uri}/devices/{device_id}:
    patch:
      tags:
        - messages
      summary: Notify a message state update for a recipient device.
      description: Notify a message state update for a recipient device.
      operationId: notifyMessageDeviceResponse
      parameters:
        - name: message_id
          in: path
          description: ID of message to patch
          required: true
          schema:
            type: string
        - name: sip_uri
          in: path
          description: SIP address of the recipient
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: Device id of recipient, might be an url if no ID exist.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid message_id/to/device_id supplied
        '404':
          description: Message/To not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageDeviceResponse'

  #####################################################################################
  ############################# call ##################################################
  #####################################################################################
  /calls:
    post:
      tags:
        - calls
      summary: Add information about a new call
      description: Add information about a new call
      operationId: addCall
      responses:
        '200':
          description: Successful operation
        '422':
          description: Invalid input
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Call'
  /calls/{call_id}/devices/{device_id}:
    patch:
      tags:
        - calls
      summary: Update call on status update (ringing, accepted...), by device.
      operationId: updateCallDeviceState
      parameters:
        - name: call_id
          in: path
          description: ID of call to patch
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: Device id of recipient, might be an url if no ID exist.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid call_id/device_id supplied
        '404':
          description: Call not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallDeviceState'
  /calls/{call_id}:
    patch:
      tags:
        - calls
      summary: Update call on BYE.
      operationId: updateCallState
      parameters:
        - name: call_id
          in: path
          description: ID of call to patch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid call_id supplied
        '404':
          description: Call not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - ended_at
              properties:
                ended_at:
                  type: string
                  format: date-time
                  example: 2017-07-21T19:42:26Z

  #####################################################################################
  ############################# conference ############################################
  #####################################################################################
  /conferences:
    post:
      tags:
        - conferences
      summary: Add information about a new conference
      description: Add information about a new conference
      operationId: addConference
      responses:
        '200':
          description: Successful operation
        '422':
          description: Invalid input
      security:
        - api_key: []
      requestBody:
        description: Create a new call
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Conference'
  /conferences/{conference_id}:
    patch:
      tags:
        - conferences
      summary: Notify that a conference ended
      operationId: notifyConferenceEnded
      parameters:
        - name: conference_id
          in: path
          description: ID of conference to patch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid conference_id supplied
        '404':
          description: Conference not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ended_at:
                  type: string
                  format: date-time
                  example: 2017-07-21T17:32:28Z
  /conferences/{conference_id}/participants/{sip_uri}/events:
    post:
      tags:
        - conferences
      summary: Notify a participant event
      operationId: conferenceAddParticipantEvent
      parameters:
        - name: conference_id
          in: path
          description: ID of conference to patch
          required: true
          schema:
            type: string
        - name: sip_uri
          in: path
          description: SIP address of the participant
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid conference_id supplied
        '404':
          description: Conference not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantEvent'
  /conferences/{conference_id}/participants/{sip_uri}/devices/{device_id}/events:
    post:
      tags:
        - conferences
      summary: Notify a participant device event
      operationId: conferenceAddParticipantDeviceEvent
      parameters:
        - name: conference_id
          in: path
          description: ID of conference to patch
          required: true
          schema:
            type: string
        - name: sip_uri
          in: path
          description: SIP address of the participant
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          description: Device uuid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        '400':
          description: Invalid conference_id supplied
        '404':
          description: Conference not found
        '422':
          description: Validation exception
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantDeviceEvent'

#####################################################################################
############################# components ############################################
#####################################################################################
components:
  schemas:
    ############################# message ###############################################
    MessageDevices:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/MessageDeviceResponse'
      example:
        device_id_1:
          last_status: 200
          received_at: "2017-07-21T17:32:28Z"
        device_id_2:
          last_status: 408
          received_at: "2017-07-21T17:32:28Z"
        device_id_3: null

    MessageDeviceResponse:
      nullable: true
      required:
          - last_status
          - received_at
      properties:
        last_status:
          type: number
          example: 200
        received_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z

    Message:
      required:
        - id
        - from
        - to
        - sent_at
        - encrypted
      properties:
        id:
          type: string
          format: uuid
          example: 84c937d1-f1b5-475d-adb7-b41b78b078d4
        from:
          type: string
          format: sip-address
          example: user@sip.linphone.org
        to:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MessageDevices'
          example :
            user1@domain.org:
              device_id_1:
                last_status: 200
                received_at: "2017-07-21T17:32:28Z"
              device_id_2:
                last_status: 408
                received_at: "2017-07-21T17:32:28Z"
              device_id_3: null
            user2@domain.org:
              device_id_1:
                last_status: 503
                received_at: "2017-07-21T17:32:28Z"
              device_id_2: null
        sent_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        encrypted:
          type: boolean
        conference_id:
          type: string
          nullable: true
          example: iHVDMq6MxSKp60bT

    ############################# call ###############################################
    Terminated:
      required:
        - at
        - state
      properties:
        at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        state:
          type: string
          description: Call status
          enum:
            - error
            - declined
            - canceled
            - accepted_elsewhere
            - declined_elsewhere
            - accepted

    CallDevices:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CallDeviceState'
      example:
        device_id_1:
          rang_at: 2017-07-21T17:32:28Z
          invite_terminated:
            at: 2017-07-21T18:32:28Z
            state: accepted
        device_id_2:
          rang_at: 2017-07-21T17:32:28Z
          invite_terminated:
            at: 2017-07-21T18:32:28Z
            state: accepted_elsewhere
        device_id_3: null

    CallDeviceState:
      nullable: true
      properties:
        rang_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        invite_terminated:
          $ref: '#/components/schemas/Terminated'

    Call:
      required:
        - id
        - from
        - to
        - initiated_at
      properties:
        id:
          type: string
          example: 4722b0233fd8cafad3cdcafe5510fe57
        from:
          type: string
          format: sip-address
          example: user@sip.linphone.org
        to:
          type: string
          format: sip-address
          example: user@sip.linphone.org
        devices:
          $ref: '#/components/schemas/CallDevices'
        initiated_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        ended_at:
          type: string
          nullable: true
          format: date-time
          example: 2017-07-21T19:42:26Z
        conference_id:
          type: string
          nullable: true
          example: iHVDMq6MxSKp60bT

    ############################# conference ###############################################
    Conference:
      required:
       - id
       - created_at
      properties:
        id:
          type: string
          example: iHVDMq6MxSKp60bT
        created_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        ended_at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z
        schedule:
          type: string

    ParticipantEvent:
      required:
        - type
        - at
      properties:
        type:
          type: string
          description: Participant event type
          enum:
            - added
            - left
            - removed
        at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z

    ParticipantDeviceEvent:
      required:
        - type
        - at
      properties:
        type:
          type: string
          description: Participant event type
          enum:
            - invited
            - joined
            - left
            - error
        at:
          type: string
          format: date-time
          example: 2017-07-21T17:32:28Z

  ############################# securitySchemes ###############################################
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header