From 1f5ebdafd83a7bda73aca8675c9a96cf10a8fa8e Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Mon, 9 Dec 2024 10:01:50 +0100 Subject: [PATCH] feat(callhandling): VvoipSessionInformation schema reviewed --- .../BYON-CallHandling-Service.yaml | 209 +++++++----------- 1 file changed, 82 insertions(+), 127 deletions(-) diff --git a/code/API_definitions/BYON-CallHandling-Service.yaml b/code/API_definitions/BYON-CallHandling-Service.yaml index 1916440..32ecf8a 100644 --- a/code/API_definitions/BYON-CallHandling-Service.yaml +++ b/code/API_definitions/BYON-CallHandling-Service.yaml @@ -1,13 +1,21 @@ openapi: 3.0.3 info: title: Bring Your Own Number (BYON) call handling API (VVOIP Service) - description: APIs for REST clients for 1-1 calling + description: |- + ## APIs for REST clients for 1-1 calling + + API to create 1-1 voice and video sessions. These, identified by a unique `vvoipSessionId` + can be recovered, updated and terminated via this API and its methods. + - **POST**: Create a new session using a valid `clientId` from RACM API + - **GET**: Recover an existing session via its unique `vvoipSessionId` + - **DELETE**: Finish an existing session via its unique `vvoipSessionId` + - **PUT**: Update the status of a session via its unique `vvoipSessionId` contact: email: contact@domain.com license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' - version: 0.1.2 + version: 0.1.3 servers: - url: '{apiRoot}/vvoip/{apiVersion}' variables: @@ -37,14 +45,9 @@ 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 + examples: + VVOIP session request: + $ref: '#/components/examples/exVSIRequest' responses: '201': description: Created @@ -73,9 +76,11 @@ paths: - OneToOneCall summary: Get the vvoip session information description: | - Get the VVoIP Session description based on vvoipSessionId. + Get the VVoIP Session description based on `vvoipSessionId`. - ** The client shall construct the API path using the vvoipSessionId 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' @@ -154,7 +159,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ReceiverSessionStatus' + $ref: '#/components/schemas/VvoipSessionInformation' examples: MT183: $ref: '#/components/examples/exMT183' @@ -172,7 +177,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ReceiverSessionStatus' + $ref: '#/components/schemas/VvoipSessionInformation' examples: Hold: $ref: '#/components/examples/exMTHold' @@ -197,123 +202,89 @@ paths: components: schemas: VvoipSessionInformation: - required: - - originatorAddress - - receiverAddress type: object properties: originatorAddress: $ref: '#/components/schemas/Address' originatorName: type: string - description: Friendly name of the originator - example: originator + description: Friendly name of the call originator + example: 'Alice' receiverAddress: $ref: '#/components/schemas/Address' receiverName: type: string - description: Friendly name of the receiver - example: receiver + description: Friendly name of the call terminator + example: 'Bob' status: $ref: '#/components/schemas/SessionStatus' offer: - $ref: '#/components/schemas/WrtcsOffer' + $ref: '#/components/schemas/WrtcSDPDescriptor' answer: - $ref: '#/components/schemas/WrtcsAnswer' + $ref: '#/components/schemas/WrtcSDPDescriptor' 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. + 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. + example: 1c1c3e8d-8f9d-4167-ac78-929ba0b21051 vvoipSessionId: type: string - 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. - example: 0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EFAAF209EE52FD0BECC5B7CDE645F50DE7D - SessionInvitationNotification: - required: - - originatorAddress - type: object - properties: - originatorAddress: - $ref: '#/components/schemas/Address' - originatorName: - type: string - description: Friendly name of the call originator - example: originator - receiverAddress: - $ref: '#/components/schemas/Address' - receiverName: - type: string - description: Friendly name of the call receiver - example: receiver - offer: - $ref: '#/components/schemas/WrtcsOffer' - answer: - $ref: '#/components/schemas/WrtcsAnswer' + 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. + example: 0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF callObjectRef: type: string description: The reference to the call object + example: 84c742ba-a117-4e38-a089-1545073ce15c serverCorrelator: type: string description: >- - A correlator that the server instructs the client to use for end to - end correlation. The server shall use the end to end correlator - generated by the network to signal the client to use it for end to - end correlation. This field can be used in the Quality-of-Experience - (QoE) reports - SessionStatusNotification: - required: - - status - type: object - properties: - status: - $ref: '#/components/schemas/SessionStatus' - offer: - $ref: '#/components/schemas/WrtcsOffer' - answer: - $ref: '#/components/schemas/WrtcsAnswer' - receiverName: - type: string - description: Name of the receiver - receiverAddress: - $ref: '#/components/schemas/Address' - callObjectRef: - type: string - description: Call object reference - format: url + A correlator that the server instructs the client to use for end to end correlation. + example: 1492d270-8ca6-4367-9d1b-edd2fbd7f81b offerRequired: type: boolean description: >- - This element shall be included and set to true, if the session - updates are received without SDP offer. This element indicates - clients to send the offer. - serverCorrelator: - type: string - description: >- - A correlator that the server instructs the client to use for end to - end correlation. The server shall use the end to end correlator - generated by the network to signal the client to use it for end to - end correlation. This field can be used in the Quality-of-Experience - (QoE) reports + This element shall be included and set to true, if the session updates are received + without SDP offer. This element indicates clients to send the offer. + example: false reason: type: string - description: | - The description of the event that has happened within the session + description: The description of the event that has happened within the session + example: 183 Progress sequenceNumber: - type: string + type: integer description: The sequence number of the notification sent to client - ReceiverSessionStatus: + example: 345 + WrtcSDPDescriptor: type: object + description: |- + **OFFER**: 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. + + **ANSWER**: 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. properties: - status: - $ref: '#/components/schemas/SessionStatus' - offer: - $ref: '#/components/schemas/WrtcsOffer' - answer: - $ref: '#/components/schemas/WrtcsAnswer' - receiverName: + sdp: type: string - description: Name of the receiver - receiverAddress: - $ref: '#/components/schemas/Address' + 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 + SessionNotification: + allOf: + - $ref: '#/components/schemas/VvoipSessionInformation' + required: + - status + - vvoipSessionId SessionStatus: type: string description: Provides the status of the VVOIP session. During the session creation, this attribute SHALL NOT be included in the request. @@ -333,34 +304,7 @@ components: - NoAnswer - NotReachable - Busy - 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]. - 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. + example: Ringing ErrorInfo: type: object properties: @@ -379,7 +323,7 @@ components: - message Address: type: string - description: Sender or Receiver address + description: Subscriber address (Sender or Receiver) pattern: '^(tel:+[0-9]{5,15}|sip:.+@.+|.+)$' example: 'tel:+11234567899' parameters: @@ -411,14 +355,25 @@ components: schema: type: string examples: + exVSIRequest: + value: + originatorAddress: tel:+17085852753 + originatorName: tel:+17085852753 + receiverAddress: tel:+17085854000 + receiverName: tel:+17085854000 + offer: + 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 exVSIResponse: value: originatorAddress: 'tel:+17085852753' originatorName: 'tel:+17085852753' receiverAddress: 'tel:+17085854000' receiverName: 'tel:+17085854000' - status: Initial clientCorrelator: fda6e26d-e7c8-4596-870c-c083c0d39b2c + offer: + 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" + status: Initial vvoipSessionId: 0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD3F90AE0CEB9EEB0C0F703E199FC00E7C6E648F50EE885FF0CE6C7E1CEE795EDD exMT183: value: