diff --git a/code/API_definitions/BYON-CallHandling-Service.yaml b/code/API_definitions/BYON-CallHandling-Service.yaml index 9aa8bf8..10dbef2 100644 --- a/code/API_definitions/BYON-CallHandling-Service.yaml +++ b/code/API_definitions/BYON-CallHandling-Service.yaml @@ -37,6 +37,14 @@ paths: application/json: schema: $ref: '#/components/schemas/VvoipSessionInformation' + example: + originatorAddress: tel:+17085852753 + originatorName: tel:+17085852753 + receiverAddress: tel:+17085854000 + receiverName: tel:+17085854000 + answer: + sdp: "v=0\r\no=- 8066321617929821805 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 42988 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:2448:7a05:9b11:66f2:c9e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:1645903805 1 udp 2122262783 2001:e0:410:2448:7a05:9b11:66f2:c9e 42988 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:4eKp\r\na=ice-pwd:D4sF5Pv9vx9ggaqxBlHbAFMx\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:Xm3YciqVIWFNSwy19e9MvfZ2YOdAZil7oT/tHjdf\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\n" + clientCorrelator: fda6e26d-e7c8-4596-870c-c083c0d39b2c responses: '400': $ref: '#/components/responses/Generic400' @@ -50,22 +58,20 @@ paths: - BearerAuth: - read - write - /sessions/{sessionId}: + /sessions/{vvoipSessionId}: get: tags: - OneToOneCall summary: Get the vvoip session information - description: > - Get the VVoIP Session description based on sessionId. - + description: | + Get the VVoIP Session description based on vvoipSessionId. - **Client shall use the resourceUrl supplied in the session creation - response (origination) or in the invitation notification (termination)** + ** The client shall construct the API path using the vvoipSessionId supplied in the session creation response (origination) or in the invitation notification (termination). ** operationId: getSessionDetailsById parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' - - $ref: '#/components/parameters/pathParamSessionId' + - $ref: '#/components/parameters/pathParamVvoipSessionId' responses: '200': description: A session information @@ -98,15 +104,12 @@ paths: 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)**' + ** The client shall construct the API path using the vvoipSessionId supplied in the session creation response (origination) or in the invitation notification (termination). **' operationId: deleteSessionById parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' - - $ref: '#/components/parameters/pathParamSessionId' + - $ref: '#/components/parameters/pathParamVvoipSessionId' responses: '204': description: Session deleted @@ -124,19 +127,20 @@ paths: - BearerAuth: - read - write - /sessions/{sessionId}/status: + /sessions/{vvoipSessionId}/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 + description: | + Update the status of the vvoip session, this may include updating SDP media + + ** The client shall construct the API path using the vvoipSessionId supplied in the session creation response (origination) or in the invitation notification (termination). **' operationId: postSessionStatus parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' - - $ref: '#/components/parameters/pathParamSessionId' + - $ref: '#/components/parameters/pathParamVvoipSessionId' requestBody: content: application/json: @@ -194,24 +198,10 @@ components: $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: + 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. + vvoipSessionId: 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} + description: The VVOIP session ID created by WebRTC Gateway. The vvoipSessionID shall not be included in POST requests by the client, but must be included in the notifications from the WebRTC GW to client. SessionInvitationNotification: required: - originatorAddress @@ -400,8 +390,8 @@ components: explode: false schema: type: string - pathParamSessionId: - name: sessionId + pathParamVvoipSessionId: + name: vvoipSessionId in: path description: The sessionId assigned by the WebRTC GW for the vvoip session required: true @@ -418,8 +408,7 @@ components: receiverName: tel:+17085854000 status: Initial clientCorrelator: fda6e26d-e7c8-4596-870c-c083c0d39b2c - resourceURL: >- - $url/sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD + vvoipSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD exMT183: value: receiverSessionStatus: diff --git a/code/API_definitions/BYON-Notification-Channel.yaml b/code/API_definitions/BYON-Notification-Channel.yaml index e17db5f..669fac0 100644 --- a/code/API_definitions/BYON-Notification-Channel.yaml +++ b/code/API_definitions/BYON-Notification-Channel.yaml @@ -2,15 +2,15 @@ openapi: 3.0.0 info: title: Bring Your Own Number (BYON) Notification Channel APIs description: This API provide REST API for a client, browser or native application, to establish notification channel to receive asynchronous notifications from MNO's IMS Network. - version: 0.1.0 + version: 0.1.1 contact: email: contact@domain.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: -- url: '{apiRoot}/notificationchannel/{apiVersion}/{deviceId}' - description: APIs to create Notification Channels +- url: '{apiRoot}/notificationchannel/{apiVersion}' + description: APIs to create and manage Notification Channels variables: apiRoot: description: API Root @@ -18,34 +18,96 @@ servers: apiVersion: description: The version of API to be used default: v1 - deviceId: - description: "The notification channel creation is specific to a device instance, the device-id in the uuid format (rfc4412) shall be included in the request" - default: 'deviceId' tags: - name: Notification Channel description: APIs for establishing notification channel to receive asynchronous notifications from MNO's IMS network paths: - /channels: + /channels/{channelId}: get: - description: Retrieves the list of Notification Channels + tags: + - Notification Channel + summary: Retrieves Notification Channel + description: '**The client shall use the racmSessionId to construct the API path**' parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' + - $ref: '#/components/parameters/pathParamChannelId' responses: "200": description: Success content: application/json: schema: - $ref: '#/components/schemas/NotificationChannelList' - "403": - $ref: '#/components/responses/Generic403' + $ref: '#/components/schemas/NotificationChannel' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '404': + $ref: '#/components/responses/NotFound404' + '500': + $ref: '#/components/responses/Generic500' security: - BearerAuth: - read - write + put: + tags: + - Notification Channel + summary: Update Notification Channel properties e.g., expire time, tokens + description: '**The client shall use racmSessionId to construct API path**' + parameters: + - $ref: '#/components/parameters/hdrTransactionId' + - $ref: '#/components/parameters/hdrClientId' + - $ref: '#/components/parameters/pathParamChannelId' + responses: + "201": + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationChannel' + '204': + description: No Content + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '404': + $ref: '#/components/responses/NotFound404' + '500': + $ref: '#/components/responses/Generic500' + security: + - BearerAuth: + - read + - write + delete: + tags: + - Notification Channel + summary: Delete Notification Channel + description: '**The client shall use racmSessionId to construct API path**' + parameters: + - $ref: '#/components/parameters/hdrTransactionId' + - $ref: '#/components/parameters/hdrClientId' + - $ref: '#/components/parameters/pathParamChannelId' + responses: + '204': + description: No Content + '401': + $ref: '#/components/responses/Generic401' + '404': + $ref: '#/components/responses/NotFound404' + '500': + $ref: '#/components/responses/Generic500' + security: + - BearerAuth: + - read + - write + /channels: post: - description: Create notification channel(s) + tags: + - Notification Channel + description: Create notification channel parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' @@ -53,18 +115,22 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/NotificationChannelsInformation' + $ref: '#/components/schemas/NotificationChannel' responses: - "200": - description: Success + "201": + description: Created content: application/json: schema: - $ref: '#/components/schemas/NotificationChannelsInformation' - "403": - description: Forbidden - "409": - description: Conflict + $ref: '#/components/schemas/NotificationChannel' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '500': + $ref: '#/components/responses/Generic500' security: - BearerAuth: - read @@ -78,8 +144,8 @@ components: hdrClientId: name: clientId in: header - description: The Client ID assigned by WebRTC GW - required: true + description: The Client ID provided by the WebRTC Gateway is necessary solely if the notification channel is created by the gateway itself. + required: false style: simple explode: false schema: @@ -93,6 +159,15 @@ components: explode: false schema: type: string + pathParamChannelId: + name: channelId + in: path + description: The Channel ID associated with the request + required: true + style: simple + explode: false + schema: + type: string schemas: ChannelType: @@ -101,7 +176,31 @@ components: enum: - WebSockets - PNSChannel - + - Webhook + + WebhookData: + properties: + webhook: + $ref: '#/components/schemas/Webhook' + expiresAt: + type: string + format: date-time + description: Time indicating when the channel will expire if it is not renewed. + example: "2024-02-29T12:00:00Z" + + Webhook: + type: object + properties: + notificationUrl: + type: string + description: URL of the webhook endpoint. + format: uri + example: https://example.com/webhooks + notificationAuthToken: + type: string + description: (Optional) Secret used for authentication with the webhook. + example: "your_secret_key" + WebSocketsData: properties: channelURL: @@ -128,32 +227,12 @@ components: oneOf: - $ref: '#/components/schemas/WebSocketsData' - $ref: '#/components/schemas/PNSChannelData' - resourceURL: - type: string - description: "Self referring URL. The resourceURL SHALL NOT be included in POST requests by the client, but MUST be included in POST requests representing notifications by the server to the client, when a complete representation of the resource is embedded in the notification. The resourceURL MUST be also included in responses to any HTTP method that returns an entity body, and in PUT requests." - callbackURL: + - $ref: '#/components/schemas/WebhookData' + channelId: type: string - description: This will be specified by the server and contains the callback URL used when establishing subscription for notifications from service providing servers. + description: Notification Channel ID. The clients are required to construct API path using this ID. - NotificationChannelList: - type: object - properties: - channels: - type: array - items: - $ref: '#/components/schemas/NotificationChannel' - resourceURL: - type: string - description: Self referring URL - NotificationChannelsInformation: - type: object - properties: - channels: - type: array - items: - $ref: '#/components/schemas/NotificationChannel' - ErrorInfo: type: object properties: @@ -213,7 +292,7 @@ components: code: CONFLICT message: 'Simultaneous channel requests not supported' NotFound404: - description: Session Not found + description: Channel Not found content: application/json: schema: @@ -221,7 +300,7 @@ components: example: status: 404 code: NOT_FOUND - message: Unable to find the session with the provided Id parameters + message: Unable to find the channel with the provided Id Generic500: description: Internal server error content: diff --git a/code/API_definitions/BYON-RACM-Service.yaml b/code/API_definitions/BYON-RACM-Service.yaml index b15a7de..fc5f44e 100644 --- a/code/API_definitions/BYON-RACM-Service.yaml +++ b/code/API_definitions/BYON-RACM-Service.yaml @@ -2,7 +2,7 @@ openapi: 3.0.0 info: title: Bring Your Own Number (BYON) Registration and Connectivity Management (RACM) Service APIs description: This API provide REST API for clients to manage Registration and Connectivity (RACM) towards MNO's IMS Network. - version: 0.1.0 + version: 0.1.2 contact: email: contact@domain.com license: @@ -22,7 +22,7 @@ tags: - name: Registration and Connection Management description: APIs for Client to Register into MNO's IMS Network paths: - /session: + /sessions: post: tags: - RACM @@ -96,16 +96,16 @@ paths: - BearerAuth: - read - write - /session/{sessionId}: + /sessions/{racmSessionId}: put: tags: - RACM summary: For sharing new AccessToken with WebRTC GW, the AccessToken is expected to be received from the Auth server. - description: '**The client shall use the resourceUrl supplied in the session creation request. There is no need of constructing the URL**' + description: '**The client shall use the racmSessionId to construct the API path.**' parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' - - $ref: '#/components/parameters/pathParamSessionId' + - $ref: '#/components/parameters/pathParamRacmSessionId' responses: '200': description: No Content @@ -117,11 +117,11 @@ paths: tags: - RACM summary: Delete Registration Session. - description: '**The client shall use the resourceUrl supplied in the session creation request. There is no need of constructing the URL**' + description: '**The client shall use the racmSessionId to construct the API path.**' parameters: - $ref: '#/components/parameters/hdrTransactionId' - $ref: '#/components/parameters/hdrClientId' - - $ref: '#/components/parameters/pathParamSessionId' + - $ref: '#/components/parameters/pathParamRacmSessionId' responses: '204': description: No Content @@ -139,9 +139,10 @@ components: deviceId: type: string description: The device-id of the client in UUID format. - notificationUri: + channelId: type: string - description: The URI which need to be used by WebRTC Gateway for posting notifications towards the client. This should be filled only when the notification channel is provided by a independent notification channel provider. + description: ID of an existing notification channel. + example: "channel_id_123" RacmResponse: type: object properties: @@ -151,9 +152,9 @@ components: type: array items: $ref: '#/components/schemas/RegistrationInformation' - resourceURL: + racmSessionId: type: string - description: The resource URL allocated by WebRTC GW representing the RACM session created. The sessionId assigned for RACM session is part of the url. + description: The RACM session ID created by WebRTC Gateway. Clients must utilize this ID to construct the API path. ConnectionInformation: type: object properties: @@ -171,6 +172,7 @@ components: type: string regStatus: $ref: '#/components/schemas/RegistrationStatus' + ErrorInfo: type: object properties: @@ -206,8 +208,8 @@ components: explode: false schema: type: string - pathParamSessionId: - name: sessionId + pathParamRacmSessionId: + name: racmSessionId in: path description: The sessionId assigned by the RACM service required: true