openapi: 3.2.0
info:
  title: Bring Your Own Number (BYON) call handling API (VVOIP Service) One To One Call API
  description: APIs for REST clients for 1-1 calling
  contact:
    email: contact@mavenir.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: '{apiRoot}/vvoip/{apiVersion}/{userId}'
  variables:
    apiRoot:
      description: API root
      default: http://localhost:9091
    apiVersion:
      description: Version of the VVOIP service API
      default: v1
    userId:
      description: The public identity of the user in the URI format through which client is trying to communicate
      default: user
tags:
- name: OneToOneCall
  description: APIs related to 1-1 voice/video call session
paths:
  /sessions:
    post:
      tags:
      - OneToOneCall
      summary: Creates voice and/or video session
      description: Creates a voice and/or video session
      operationId: postSessions
      parameters:
      - name: transactionId
        in: header
        description: The Transaction  associated with the request
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientId
        in: header
        description: The Client Id assigned by WebRTC Gateway
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        description: Provide the information required for session creation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VvoipSessionInformation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VvoipSessionInformation'
              examples:
                SessionCreated:
                  $ref: '#/components/examples/exVSIResponse'
        '400':
          $ref: '#/components/responses/Generic400'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
      - BearerAuth:
        - read
        - write
  /sessions/{sessionId}:
    get:
      tags:
      - OneToOneCall
      summary: Get the vvoip session information
      description: 'Get the VVoIP Session description based on sessionId.


        **Client shall use the resourceUrl supplied in the session creation response (origination) or in the invitation notification (termination)**

        '
      operationId: getSessionDetailsById
      parameters:
      - name: transactionId
        in: header
        description: Transaction Id associated with the request
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientId
        in: header
        description: The Client Id assigned by WebRTC GW
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: The sessionId assigned by the WebRTC GW for the vvoip session
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: A session information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VvoipSessionInformation'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
      - BearerAuth:
        - read
        - write
    delete:
      tags:
      - OneToOneCall
      summary: Cancel or Terminate the vvoip session
      description: 'Cancel a 1-1 vvoip session (as originator),

        Decline a 1-1 vvoip session (as receiver),

        Terminate a 1-1 an ongoing vvoip session


        **Client shall use the resourceUrl supplied in the session creation response (origination) or in the invitation notification (termination)**''

        '
      operationId: deleteSessionById
      parameters:
      - name: transactionId
        in: header
        description: Transaction Id associated with the request
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientId
        in: header
        description: The Client Id assigned by WebRTC GW
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: The sessionId assigned by the WebRTC GW for the vvoip session
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: Session deleted
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
      - BearerAuth:
        - read
        - write
  /sessions/{sessionId}/status:
    put:
      tags:
      - OneToOneCall
      summary: Update the status of the vvoip session
      description: 'Update the status of the vvoip session, this may include updating SDP media

        '
      operationId: postSessionStatus
      parameters:
      - name: transactionId
        in: header
        description: Transaction Id associated with the request
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: clientId
        in: header
        description: The Client Id assigned by WebRTC GW
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: sessionId
        in: path
        description: The sessionId assigned by the WebRTC GW for the vvoip session
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiverSessionStatus'
            examples:
              MT183:
                $ref: '#/components/examples/exMT183'
              MT180:
                $ref: '#/components/examples/exMT180'
              MT200:
                $ref: '#/components/examples/exMT200'
      responses:
        '200':
          description: Updated the session status
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/SessionNotFound404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
      security:
      - BearerAuth:
        - read
        - write
components:
  schemas:
    ErrorInfo:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code returned along with this error response
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
      required:
      - status
      - code
      - message
    SessionStatus:
      type: string
      enum:
      - Initial
      - InProgress
      - Ringing
      - Proceeding
      - Connected
      - Terminated
      - Hold
      - Resume
      - SessionCancelled
      - Declined
      - Failed
      - Waiting
      - NoAnswer
      - NotReachable
      - Busy
    ReceiverSessionStatus:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SessionStatus'
        responseCode:
          type: integer
          description: 'Indicates corresponding SIP response code, mainly used for provisional responses (status set to “InProgress”, “Ringing”) Possible values are 180, 183, 200, if any other values are set, then the behavior is undefined or unknown. When the client sets the status as “Hold”, the responseCode element be set to 200. Web RTC gateway shall be use this to determins WebRTC GW if it''s a hold request or response to hold notification sent earlier.

            '
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        receiverName:
          type: string
          description: Name of the receiver
        receiverAddress:
          type: string
          description: Address (e.g. 'sip' URI, 'tel' URI, 'acr' URI) of the receiver
    VvoipSessionInformation:
      required:
      - originatorAddress
      - receiverAddress
      type: object
      properties:
        originatorAddress:
          type: string
          description: Address of the session originator
          example: tel:+911234567890
        originatorName:
          type: string
          description: Friendly name of the originator
          example: originator
        receiverAddress:
          type: string
          description: Address of the session receiver
          example: tel:+911234567891
        receiverName:
          type: string
          description: Friendly name of the receiver
          example: receiver
        status:
          $ref: '#/components/schemas/SessionStatus'
        offer:
          $ref: '#/components/schemas/WrtcsOffer'
        answer:
          $ref: '#/components/schemas/WrtcsAnswer'
        clientCorrelator:
          type: string
          description: A correlator that the client can use to tag this particular resource representation during a request to create a resource on the server. Note - This allows the client to recover from communication failures during resource creation and therefore avoids re-sending the message in such situations. In case the element is present, the WebRTC GW shall not alter its value, and shall provide it as part of the representation of this resource.
        resourceUrl:
          type: string
          description: Self referring URL. The resourceURL shall not be included in POST requests by the client, but must be included in the notifications from the WebRTC GW to client when a complete representation of the resource is embedded in the notification. The resourceURL must also be included in responses to any HTTP method that returns an entity body, and in PUT requests
          example: $url/{sessionId}
    WrtcsAnswer:
      type: object
      properties:
        sdp:
          type: string
          description: 'An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

            '
      description: 'This type represents an answer in WebRTC Signaling. This element is not present in case there is no answer yet, or the session invitation has been declined by the Terminating Participant.This element MUST NOT be present in a request from the application to the server to create a session.

        '
    WrtcsOffer:
      type: object
      properties:
        sdp:
          type: string
          description: 'An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section

            '
      description: 'The offer, which MUST be present in a request from the application to the server to create a session. Note that the offer can be absent in a session created by the server as part of an offerless INVITE [RFC3261].

        '
  responses:
    SessionNotFound404:
      description: Session not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            message: Session Id does not exist
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: 'Authorization failed: ...'
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable
    Generic500:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: 'Internal server error: ...'
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 403
            code: PERMISSION_DENIED
            message: 'Operation not allowed: ...'
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Schema validation failed at  ...
  examples:
    exMT200:
      value:
        receiverSessionStatus:
          status: Connected
          answer:
            sdp: 'v=0

              o=- 4576312012535546667 4 IN IP4 127.0.0.1

              s=-

              t=0 0

              m=audio 47510 RTP/SAVPF 102 113

              c=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e

              b=AS:64

              a=rtcp:9 IN IP4 0.0.0.0

              a=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900

              a=ice-ufrag:47Nx

              a=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy

              a=ice-options:trickle renomination

              a=mid:audio

              a=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01

              a=sendrecv

              a=rtcp-mux

              a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz

              a=rtpmap:102 AMR-WB/16000

              a=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2

              a=rtpmap:113 telephone-event/16000

              a=ptime:20

              '
          responseCode: '200'
    exVSIResponse:
      value:
        originatorAddress: tel:+817085852753
        originatorName: 817085852753
        receiverAddress: tel:+817085854000
        receiverName: 817085854000
        status: Initial
        clientCorrelator: fda6e26d-e7c8-4596-870c-c083c0d39b2c
        resourceURL: $url/sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD
    exMT180:
      value:
        receiverSessionStatus:
          status: Ringing
          responseCode: '180'
    exMT183:
      value:
        receiverSessionStatus:
          status: InProgress
          answer:
            sdp: 'v=0

              o=- 8066321617929821805 2 IN IP4 127.0.0.1

              s=-

              t=0 0

              m=audio 42988 RTP/SAVPF 102 113

              c=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e

              b=AS:64

              a=rtcp:9 IN IP4 0.0.0.0

              a=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900

              a=ice-ufrag:4eKp

              a=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx

              a=ice-options:trickle renomination

              a=mid:audio

              a=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01

              a=sendrecv

              a=rtcp-mux

              a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf

              a=rtpmap:102 AMR-WB/16000

              a=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2

              a=rtpmap:113 telephone-event/16000

              '
          responseCode: '183'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer