From e83fc8ae8d9efd3b504c9acc61a7a0e81f65d70b Mon Sep 17 00:00:00 2001 From: Santiago Troncoso Date: Thu, 24 Oct 2024 15:30:26 +0200 Subject: [PATCH] WIP --- .../BYON-Notification-Channel_new.yaml | 1167 +++++++++++++++++ code/API_definitions/BYON-RACM-Service.yaml | 4 +- .../uml-diagrams/FlowsBYON-CallHandling.wsd | 133 +- .../FlowsBYON-NotificationChannel.wsd | 51 +- 4 files changed, 1273 insertions(+), 82 deletions(-) create mode 100644 code/API_definitions/BYON-Notification-Channel_new.yaml diff --git a/code/API_definitions/BYON-Notification-Channel_new.yaml b/code/API_definitions/BYON-Notification-Channel_new.yaml new file mode 100644 index 0000000..e60018e --- /dev/null +++ b/code/API_definitions/BYON-Notification-Channel_new.yaml @@ -0,0 +1,1167 @@ +openapi: 3.0.3 +info: + title: BYON Notification Subscription + description: | + ## Introduction + + This API provide REST API for a client, browser or native application, to + establish a notification channel (cloudevent.io compliant) for + asynchronous events on the different BYON (Bring Your Own Number) usecases. + + ## Relevant terms and defitnions + + - **BYON**: Bring Your Own Number. A commercial name for the functionality to use your telco + credentials and phone number identity to no-SIM devices using WebRTC sessions + - **session**: A media session, an exchange of media between endpoints, usually knonw as a + "single one-to-one call". + - **registration**: An endpoint status were it is properly identified to be reachable by the + server side of the WebRTC gateway. + + ## API functionality + + The CAMARA subscription model is detailed in the CAMARA API design guideline document and + follows CloudEvents specification. + + This API allows to create an explicit notification channel for two types of events. + It is mandatory in the subscription to provide the event type for which the client would + like to subscribe. + + Following event types are managed for this API: + + - `org.camaraproject.notificationchannel.session` + + - Events triggered for any media session related event (e.g. far end new media endpoints) + + - `org.camaraproject.notificationchannel.registration` + + - Events triggered for any media endpoint registration event (e.g. incomming session) + + Note: Additionally to these list, ``org.camaraproject.notificationchannel.subscription-ends`` + notification `type` is sent when the subscription ends. + This notification does not require dedicated subscription. + + It is used when: + - the subscription expire time (optionally set by the requester) has been reached + - the maximum number of subscription events (optionally set by the requester) has been reached + - the subscription was deleted by the requester + - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached + - the API server has to stop sending notification prematurely + - the specified geofence-`area` cannot be covered or is too small to be managed + + ## Authorization and authentication + + The "Camara Security and Interoperability Profile" provides details on how a client requests + an access token. Please refer to Identify and Consent Management + (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of + the Profile. + + Which specific authorization flows are to be used will be determined during onboarding process, + happening between the API Client and the API Provider, taking into account the declared purpose + for accessing the API, while also being subject to the prevailing legal framework dictated by + local legislation. + + It is important to remark that in cases where personal user data is processed by the API, and + users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of + 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict + compliance with user privacy preferences and regulatory obligations, upholding the principles + of transparency and user-centric data control. + + ## Further info and support + (FAQs will be added in a later version of the documentation) + + ### USECASES TO COVER + ![TODO](https://www.iconninja.com/files/959/332/876/checklist-inventory-icon.png) + - Functional: + - A push notitification service based on an external webhook + - A browser that requires a WS to receive events from the server side + - Observability: + - A monitoring system that wants to monitor registration status of endpoints + - A call audit application that requires to remotly monitor call status + + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 0.1.0 + x-camara-commonalities: 0.4.0 + +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/ +servers: + - url: "{apiRoot}/notificationchannel/v1" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + 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: notificationchannel Subscription + description: Operations to manage event subscriptions on event-type event + +paths: + /subscriptions: + post: + tags: + - notificationchannel Subscription + summary: "Create a notificationchannel event subscription" + description: Create a notificationchannel event subscription + operationId: createNotificationChannelSubscription + parameters: + - $ref: "#/components/parameters/x-correlator" + security: + - openId: + - api-name:event-type:grant-level + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionRequest" + required: true + callbacks: + notifications: + "{$request.body#/sink}": + post: + summary: "notifications callback" + description: | + Important: this endpoint is to be implemented by the API consumer. + The notificationchannel server will call this endpoint whenever a notificationchannel event occurs. + `operationId` value will have to be replaced accordingly with WG API specific semantic + operationId: postNotification + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + required: true + content: + application/cloudevents+json: + schema: + $ref: "#/components/schemas/CloudEvent" + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - {} + - notificationsBearerAuth: [] + + responses: + "201": + description: Created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + "202": + description: Request accepted to be processed. It applies for async creation process. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionAsync" + "400": + $ref: "#/components/responses/CreateSubscriptionBadRequest400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/SubscriptionPermissionDenied403" + "409": + $ref: "#/components/responses/Generic409" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + get: + tags: + - notificationchannel Subscription + summary: "Retrieve a list of notificationchannel event subscription" + description: Retrieve a list of notificationchannel event subscription(s) + operationId: retrieveNotificationChannelSubscriptionList + parameters: + - $ref: "#/components/parameters/x-correlator" + security: + - openId: + - api-name:read + responses: + "200": + description: List of event subscription details + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + type: array + minItems: 0 + items: + $ref: '#/components/schemas/Subscription' + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + /subscriptions/{subscriptionId}: + get: + tags: + - notificationchannel Subscription + summary: "Retrieve a notificationchannel event subscription" + description: retrieve notificationchannel subscription information for a given subscription. + operationId: retrieveNotificationChannelSubscription + security: + - openId: + - api-name:read + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "200": + description: OK + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + "400": + $ref: "#/components/responses/SubscriptionIdRequired" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + delete: + tags: + - notificationchannel Subscription + summary: "Delete a notificationchannel event subscription" + operationId: deleteNotificationChannelSubscription + description: delete a given notificationchannel subscription. + security: + - openId: + - api-name:delete + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "204": + description: notificationchannel subscription deleted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + "202": + description: Request accepted to be processed. It applies for async deletion process. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionAsync" + "400": + $ref: "#/components/responses/SubscriptionIdRequired" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + notificationsBearerAuth: + type: http + scheme: bearer + bearerFormat: "{$request.body#/sinkCredential.credentialType}" + parameters: + SubscriptionId: + name: subscriptionId + in: path + description: Subscription identifier that was obtained from the create event subscription operation + required: true + schema: + $ref: "#/components/schemas/SubscriptionId" + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + schemas: + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + + SubscriptionRequest: + description: The request for creating a event-type event subscription + type: object + required: + - sink + - protocol + - config + - types + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: + $ref: "#/components/schemas/SinkCredential" + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided + at API project level. + type: array + minItems: 1 + maxItems: 1 + items: + type: string + config: + $ref: "#/components/schemas/Config" + discriminator: + propertyName: protocol + mapping: + HTTP: "#/components/schemas/HTTPSubscriptionRequest" + MQTT3: "#/components/schemas/MQTTSubscriptionRequest" + MQTT5: "#/components/schemas/MQTTSubscriptionRequest" + AMQP: "#/components/schemas/AMQPSubscriptionRequest" + NATS: "#/components/schemas/NATSSubscriptionRequest" + KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest" + + Protocol: + type: string + enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] + description: Identifier of a delivery protocol. Only HTTP is allowed for now + example: "HTTP" + + Config: + description: | + Implementation-specific configuration parameters needed by the subscription manager for acquiring events. + In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` + Specific event type attributes must be defined in `subscriptionDetail` + Note: if a request is performed for several event type, all subscribed event will use same `config` parameters. + type: object + required: + - subscriptionDetail + properties: + subscriptionDetail: + $ref: "#/components/schemas/CreateSubscriptionDetail" + subscriptionExpireTime: + type: string + format: date-time + example: 2023-01-17T13:18:23.682Z + description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it. + subscriptionMaxEvents: + type: integer + description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it. + minimum: 1 + example: 5 + initialEvent: + type: boolean + description: | + Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request. + Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered + Up to API project decision to keep it. + + SinkCredential: + description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + type: object + properties: + credentialType: + type: string + enum: + - PLAIN + - ACCESSTOKEN + - REFRESHTOKEN + description: "The type of the credential." + discriminator: + propertyName: credentialType + mapping: + PLAIN: "#/components/schemas/PlainCredential" + ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" + REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" + required: + - credentialType + PlainCredential: + type: object + description: A plain credential as a combination of an identifier and a secret. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + required: + - identifier + - secret + properties: + identifier: + description: The identifier might be an account or username. + type: string + secret: + description: The secret might be a password or passphrase. + type: string + AccessTokenCredential: + type: object + description: An access token credential. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + type: string + enum: + - bearer + required: + - accessToken + - accessTokenExpiresUtc + - accessTokenType + RefreshTokenCredential: + type: object + description: An access token credential with a refresh token. + allOf: + - $ref: "#/components/schemas/SinkCredential" + - type: object + properties: + accessToken: + description: REQUIRED. An access token is a previously acquired token granting access to the target resource. + type: string + accessTokenExpiresUtc: + type: string + format: date-time + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + accessTokenType: + description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). + type: string + enum: + - bearer + refreshToken: + description: REQUIRED. An refresh token credential used to acquire access tokens. + type: string + refreshTokenEndpoint: + type: string + format: uri + description: REQUIRED. A URL at which the refresh token can be traded for an access token. + required: + - accessToken + - accessTokenExpiresUtc + - accessTokenType + - refreshToken + - refreshTokenEndpoint + + CreateSubscriptionDetail: + description: The detail of the requested event subscription. + type: object + required: + - deviceId + properties: + deviceId: + type: string + example: 1qazxsw23edc + + EventTypeNotification: + type: string + description: | + event-type - Event triggered when an event-type event occurred + + subscription-ends: Event triggered when the subscription ends + enum: + - org.camaraproject.api-name.v0.event-type + - org.camaraproject.api-name.v0.subscription-ends + + Subscription: + description: Represents a event-type subscription. + type: object + required: + - sink + - protocol + - config + - types + - id + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: The address to which events shall be delivered using the selected protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: + $ref: '#/components/schemas/SinkCredential' + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided + at API project level. + type: array + minItems: 1 + maxItems: 1 + items: + type: string + config: + $ref: '#/components/schemas/Config' + id: + $ref: '#/components/schemas/SubscriptionId' + startsAt: + type: string + format: date-time + description: Date when the event subscription will begin/began + expiresAt: + type: string + format: date-time + description: Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that. + status: + type: string + description: |- + Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details: + - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet. + - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative. + - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. + - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event. + - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept). + enum: + - ACTIVATION_REQUESTED + - ACTIVE + - EXPIRED + - INACTIVE + - DELETED + discriminator: + propertyName: protocol + mapping: + HTTP: '#/components/schemas/HTTPSubscriptionResponse' + MQTT3: '#/components/schemas/MQTTSubscriptionResponse' + MQTT5: '#/components/schemas/MQTTSubscriptionResponse' + AMQP: '#/components/schemas/AMQPSubscriptionResponse' + NATS: '#/components/schemas/NATSSubscriptionResponse' + KAFKA: '#/components/schemas/ApacheKafkaSubscriptionResponse' + + SubscriptionAsync: + description: Response for a event-type subscription request managed asynchronously (Creation or Deletion) + type: object + properties: + id: + $ref: "#/components/schemas/SubscriptionId" + + SubscriptionId: + type: string + description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). + example: qs15-h556-rt89-1298 + + CloudEvent: + description: The notification callback + required: + - id + - source + - specversion + - type + - time + properties: + id: + type: string + description: identifier of this event, that must be unique in the source context. + source: + $ref: "#/components/schemas/Source" + type: + $ref: "#/components/schemas/EventTypeNotification" + specversion: + type: string + description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version) + enum: + - "1.0" + datacontenttype: + type: string + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + enum: + - application/json + data: + type: object + description: Event details payload described in each CAMARA API and referenced by its type + time: + $ref: "#/components/schemas/DateTime" + discriminator: + propertyName: "type" + mapping: + org.camaraproject.api-name.v0.event-type: "#/components/schemas/Event-typeEvent" + org.camaraproject.api-name.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds" + + Source: + type: string + format: uri-reference + minLength: 1 + description: | + Identifies the context in which an event happened - be a non-empty `URI-reference` like: + - URI with a DNS authority: + * https://github.com/cloudevents + * mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique URN with a UUID: + * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Application-specific identifier: + * /cloudevents/spec/pull/123 + * 1-555-123-4567 + example: "https://notificationSendServer12.supertelco.com" + + DateTime: + type: string + format: date-time + description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. + example: "2018-04-05T17:31:00Z" + + Event-typeEvent: + description: event structure for event-type event + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + + EventSubscriptionEnds: + description: event structure for event subscription ends + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/SubscriptionEnds" + + SubscriptionEnds: + description: Event detail structure for SUBSCRIPTION_ENDS event + type: object + required: + - terminationReason + - subscriptionId + properties: + terminationReason: + $ref: "#/components/schemas/TerminationReason" + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + terminationDescription: + type: string + + TerminationReason: + type: string + description: | + - NETWORK_TERMINATED - API server stopped sending notification + - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached + - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached + - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached + - SUBSCRIPTION_DELETED - Subscription was deleted by the requester + enum: + - MAX_EVENTS_REACHED + - NETWORK_TERMINATED + - SUBSCRIPTION_EXPIRED + - ACCESS_TOKEN_EXPIRED + - SUBSCRIPTION_DELETED + + HTTPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/HTTPSettings" + + HTTPSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/HTTPSettings" + + HTTPSettings: + type: object + properties: + headers: + type: object + description: |- + A set of key/value pairs that is copied into the HTTP request as custom headers. + + NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it. + additionalProperties: + type: string + method: + type: string + description: The HTTP method to use for sending the message. + enum: + - POST + + MQTTSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/MQTTSettings" + + MQTTSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/MQTTSettings" + + MQTTSettings: + type: object + properties: + topicName: + type: string + qos: + type: integer + format: int32 + retain: + type: boolean + expiry: + type: integer + format: int32 + userProperties: + type: object + required: + - topicName + + AMQPSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/AMQPSettings" + + AMQPSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/AMQPSettings" + + AMQPSettings: + type: object + properties: + address: + type: string + linkName: + type: string + senderSettlementMode: + type: string + enum: ["settled", "unsettled"] + linkProperties: + type: object + additionalProperties: + type: string + + ApacheKafkaSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/ApacheKafkaSettings" + + ApacheKafkaSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/ApacheKafkaSettings" + + ApacheKafkaSettings: + type: object + properties: + topicName: + type: string + partitionKeyExtractor: + type: string + clientId: + type: string + ackMode: + type: integer + required: + - topicName + + NATSSubscriptionRequest: + allOf: + - $ref: "#/components/schemas/SubscriptionRequest" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/NATSSettings" + + NATSSubscriptionResponse: + allOf: + - $ref: "#/components/schemas/Subscription" + - type: object + properties: + protocolSettings: + $ref: "#/components/schemas/NATSSettings" + + NATSSettings: + type: object + properties: + subject: + type: string + required: + - subject + responses: + CreateSubscriptionBadRequest400: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_INVALID_PROTOCOL: + value: + status: 400 + code: "INVALID_PROTOCOL" + message: "Only HTTP is supported" + GENERIC_400_INVALID_CREDENTIAL: + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + GENERIC_400_INVALID_TOKEN: + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + Generic401: + description: Authentication problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + Generic403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + SubscriptionPermissionDenied403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + GENERIC_403_SUBSCRIPTION_MISMATCH: + value: + status: 403 + code: "SUBSCRIPTION_MISMATCH" + message: "Inconsistent access token for requested events subscription" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + Generic409: + description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. + Generic415: + description: Unsupported Media Type + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format + CreateSubscriptionUnprocessableEntity422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: + value: + status: 422 + code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" + message: "Multi event types subscription not managed" + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + Generic429: + description: Too Many Requests + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Generic500: + description: Server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic503: + description: Service unavailable. Typically the server is down. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + SubscriptionIdRequired: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + status: 400 + code: INVALID_ARGUMENT + message: "Client specified an invalid argument, request body or query param" + subscriptionIdRequired: + summary: subscription id is required + value: + status: 400 + code: INVALID_ARGUMENT + message: "Expected property is missing: subscriptionId" diff --git a/code/API_definitions/BYON-RACM-Service.yaml b/code/API_definitions/BYON-RACM-Service.yaml index 2f7d253..bfa7e6d 100644 --- a/code/API_definitions/BYON-RACM-Service.yaml +++ b/code/API_definitions/BYON-RACM-Service.yaml @@ -1,7 +1,9 @@ openapi: 3.0.3 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. + description: | + This API provide REST API for clients to manage Registration and Connectivity (RACM) towards + network operator IMS Network. version: 0.1.2 contact: email: contact@domain.com diff --git a/documentation/API_documentation/uml-diagrams/FlowsBYON-CallHandling.wsd b/documentation/API_documentation/uml-diagrams/FlowsBYON-CallHandling.wsd index d9a9eaa..b4476dd 100644 --- a/documentation/API_documentation/uml-diagrams/FlowsBYON-CallHandling.wsd +++ b/documentation/API_documentation/uml-diagrams/FlowsBYON-CallHandling.wsd @@ -19,7 +19,11 @@ autonumber "[0]" participant "Web\nClient" as WebClient -participant "WebRTC\ngateway" as WebRTC_GW +box "WebRTC\ngateway" +participant "Notification\nservice" as NS #LightGreen +participant "Signaling\ngateway" as GW +end box + participant "IMS\nNetwork" as IMS_Network participant "Remote\nendpoint" as RemoteEndpoint @@ -46,7 +50,7 @@ group CALL ORIGINATION [-> WebClient: User creates a call -WebClient -> WebRTC_GW : **POST /vvoip/{apiVersion}/sessions** \n\ +WebClient -> GW : **POST /vvoip/{apiVersion}/sessions** \n\ Headers:\n\ - authorization\n\ - transactionId\n\ @@ -63,7 +67,7 @@ Local or no media provided as initial request end note -WebRTC_GW -> IMS_Network: **SIP INVITE** \n\ +GW -> IMS_Network: **SIP INVITE** \n\ From: originatorAddress \n\ To: receiverAddress \n\ sdp_inital_offer @@ -74,8 +78,8 @@ To: receiverAddress \n\ sdp_inital_offer RemoteEndpoint -> IMS_Network: 100 Trying -IMS_Network -> WebRTC_GW: 100 Trying -WebRTC_GW -> WebClient: **201 Created session** \n\ +IMS_Network -> GW: 100 Trying +GW -> WebClient: **201 Created session** \n\ - originatorAddress \n\ - receiverAddress \n\ - status : "Initial" \n\ @@ -85,26 +89,31 @@ WebRTC_GW -> WebClient: **201 Created session** \n\ RemoteEndpoint -> IMS_Network: **183 Session progress** \n\ sdp_initial_response -IMS_Network -> WebRTC_GW: **183 Session progress** \n\ +IMS_Network -> GW: **183 Session progress** \n\ sdp_initial_response -WebRTC_GW --> WebClient: JSON vvoipsession status \n\ +GW --> NS: JSON vvoipsession status \n\ + - status: **InProgress** \n\ + - offer: sdp_webrtc_offer \n\ + - answer: sdp_webrtc_answer + +NS --> WebClient: JSON vvoipsession status \n\ - status: **InProgress** \n\ - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer -note right of WebRTC_GW +note right of GW Server asume ACK or notifcation service confirmation and continues end note -WebRTC_GW ->IMS_Network: PRACK \n selectedCodec \n localQoS +GW ->IMS_Network: PRACK \n selectedCodec \n localQoS IMS_Network -> RemoteEndpoint: PRACK \n selectedCodec \n localQoS RemoteEndpoint -> IMS_Network: 200 OK (PRACK) -IMS_Network -> WebRTC_GW: 200 OK (PRACK) +IMS_Network -> GW: 200 OK (PRACK) group Late media ICE discovery -WebClient <[#purple]-> WebRTC_GW: DTLS Handshake -WebClient <[#purple]-> WebRTC_GW: ICE Connectivity Check -WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ +WebClient <[#purple]-> GW: DTLS Handshake +WebClient <[#purple]-> GW: ICE Connectivity Check +WebClient -> GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ @@ -114,55 +123,55 @@ WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/stat - offer: sdp_webrtc_offer_late \n\ - answer: sdp_webrtc_answer -WebRTC_GW ->IMS_Network: UPDATE \n localQoS \n sendrecv +GW ->IMS_Network: UPDATE \n localQoS \n sendrecv IMS_Network -> RemoteEndpoint: UPDATE \n localQoS \n sendrecv RemoteEndpoint -> IMS_Network: 200 OK (UDPATE) -IMS_Network -> WebRTC_GW: 200 OK (UPDATE) +IMS_Network -> GW: 200 OK (UPDATE) -WebClient <- WebRTC_GW: **200** Updated the session status +WebClient <- GW: **200** Updated the session status end RemoteEndpoint ->IMS_Network: 180 Ringing -IMS_Network -> WebRTC_GW: 180 Ringing -WebRTC_GW --> WebClient: JSON vvoipsession status\n\ +IMS_Network -> GW: 180 Ringing +GW --> NS: JSON vvoipsession status\n\ - status: **Ringing** \n\ - offer: sdp_webrtc_offer_late \n\ - answer: sdp_webrtc_answer -note right of WebRTC_GW +note right of GW ACK from user endpoint not required - since the WebRTC_GW does nothing with + since the GW does nothing with this confirmation. end note ...Ringing timer applies... RemoteEndpoint -> IMS_Network: 200 OK (INVITE) -IMS_Network -> WebRTC_GW: 200 OK (INVITE) -WebRTC_GW --> WebClient: JSON vvoipsession status\n\ +IMS_Network -> GW: 200 OK (INVITE) +GW --> WebClient: JSON vvoipsession status\n\ - status: **Connected** \n\ - offer: sdp_webrtc_offer_late \n\ - answer: sdp_webrtc_answer -WebRTC_GW -> IMS_Network: ACK (200 Ok) +GW -> IMS_Network: ACK (200 Ok) IMS_Network -> RemoteEndpoint: ACK (200 Ok) -WebClient <--> WebRTC_GW <>: DTLS-SRTP -WebRTC_GW <--> RemoteEndpoint <>: RTP/SRTP +WebClient <--> GW <>: DTLS-SRTP +GW <--> RemoteEndpoint <>: RTP/SRTP ...Session timer applies... [-> WebClient: Hangup -WebClient -> WebRTC_GW: **DELETE /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ +WebClient -> GW: **DELETE /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ - clientId -WebRTC_GW -> IMS_Network: BYE +GW -> IMS_Network: BYE IMS_Network -> RemoteEndpoint: BYE RemoteEndpoint -> IMS_Network: 200 OK (BYE) -IMS_Network -> WebRTC_GW: 200 OK (BYE) -WebClient <- WebRTC_GW: **200** Session deleted +IMS_Network -> GW: 200 OK (BYE) +WebClient <- GW: **200** Session deleted deactivate WebClient deactivate WebClient @@ -188,9 +197,9 @@ note right WebClient - Webhooks (resourceURL) end note -WebClient <-> WebRTC_GW: **POST /racm/{apiVersion}/session** -WebClient <-> WebRTC_GW: **POST /notificationchannel/{apiVersion}/channels** -WebClient <-> WebRTC_GW <>: Notification channel established +WebClient <-> GW: **POST /racm/{apiVersion}/session** +WebClient <-> GW: **POST /notificationchannel/{apiVersion}/channels** +WebClient <-> GW <>: Notification channel established ... @@ -201,14 +210,14 @@ sdp_inital_offer IMS_Network -> RemoteEndpoint: 100 Trying -IMS_Network -> WebRTC_GW: **SIP INVITE** \n\ +IMS_Network -> GW: **SIP INVITE** \n\ From: originatorAddress \n\ To: receiverAddress \n\ sdp_inital_offer -WebRTC_GW -> IMS_Network: 100 Trying +GW -> IMS_Network: 100 Trying -WebRTC_GW --> WebClient: JSON vvoipsession status\n\ +GW --> WebClient: JSON vvoipsession status\n\ - status: **Initial** \n\ - offer: sdp_webrtc_offer \n\ - vvoipSessionId: vvoipSessionId @@ -220,23 +229,23 @@ device. end note ' Retrieve call information -WebClient -> WebRTC_GW: **GET /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ +WebClient -> GW: **GET /vvoip/{apiVersion}/sessions/{vvoipSessionId}**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ - clientId -WebClient <- WebRTC_GW: **200 OK** \n\ +WebClient <- GW: **200 OK** \n\ Body: \n\ - status: **Initial** \n\ - offer: sdp_webrtc_offer -note right WebRTC_GW +note right GW Event notification only wakes the device. All session info is gathered from the server. end note ' Initial WebClient setup -WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ +WebClient -> GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ Body: \n\ - status: **In Progress** \n\ - offer: sdp_webrtc_offer \n\ @@ -244,21 +253,21 @@ WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/stat note right of WebClient Local or no media provided as initial answer end note -WebRTC_GW -> IMS_Network: **183 SessionInProgress** \n\ +GW -> IMS_Network: **183 SessionInProgress** \n\ sdp_initial_response -WebRTC_GW -> WebClient: 200 Updated +GW -> WebClient: 200 Updated IMS_Network -> RemoteEndpoint: **183 SessionInProgress** \n\ sdp_initial_response RemoteEndpoint -> IMS_Network: PRACK \n selectedCodec \n localQoS -IMS_Network -> WebRTC_GW: PRACK \n selectedCodec \n localQoS -WebRTC_GW -> IMS_Network: 200 OK (PRACK) +IMS_Network -> GW: PRACK \n selectedCodec \n localQoS +GW -> IMS_Network: 200 OK (PRACK) IMS_Network -> RemoteEndpoint: 200 OK (PRACK) ' WebClient Media discovery group Late Media ICE discovery -WebClient <[#purple]-> WebRTC_GW: DTLS Handshake -WebClient <[#purple]-> WebRTC_GW: ICE Connectivity Check -WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ +WebClient <[#purple]-> GW: DTLS Handshake +WebClient <[#purple]-> GW: ICE Connectivity Check +WebClient -> GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ @@ -268,17 +277,17 @@ WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/stat - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer_late - WebRTC_GW ->IMS_Network: UPDATE \n localQoS \n sendrecv + GW ->IMS_Network: UPDATE \n localQoS \n sendrecv IMS_Network -> RemoteEndpoint: UPDATE \n localQoS \n sendrecv RemoteEndpoint -> IMS_Network: 200 OK (UDPATE) -IMS_Network -> WebRTC_GW: 200 OK (UPDATE) +IMS_Network -> GW: 200 OK (UPDATE) -WebRTC_GW -> WebClient: 200 Updated +GW -> WebClient: 200 Updated end [<- WebClient : Ringing -WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ +WebClient -> GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ @@ -287,12 +296,12 @@ WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/stat - status: **Ringing** \n\ - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer_late -WebRTC_GW -> WebClient: 200 Updated -WebRTC_GW -> IMS_Network: 180 Ringing +GW -> WebClient: 200 Updated +GW -> IMS_Network: 180 Ringing IMS_Network -> RemoteEndpoint: 180 Ringing [-> WebClient : Answer] -WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ +WebClient -> GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/status**\n\ Headers:\n\ - authorization\n\ - transactionId\n\ @@ -301,29 +310,29 @@ WebClient -> WebRTC_GW: **PUT /vvoip/{apiVersion}/sessions/{vvoipSessionId}/stat - status: **Connected** \n\ - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer_late -WebRTC_GW -> WebClient: 200 Updated +GW -> WebClient: 200 Updated -WebRTC_GW -> IMS_Network: 200 OK +GW -> IMS_Network: 200 OK IMS_Network -> RemoteEndpoint: 200 Ok RemoteEndpoint -> IMS_Network: ACK -IMS_Network -> WebRTC_GW: ACK -WebRTC_GW --> WebClient: JSON vvoipsession status\n\ +IMS_Network -> GW: ACK +GW --> WebClient: JSON vvoipsession status\n\ - status: **Connected** \n\ - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer_late -WebClient <--> WebRTC_GW <>: DTLS-SRTP -WebRTC_GW <--> RemoteEndpoint <>: RTP/SRTP +WebClient <--> GW <>: DTLS-SRTP +GW <--> RemoteEndpoint <>: RTP/SRTP RemoteEndpoint -> IMS_Network: BYE -IMS_Network -> WebRTC_GW: BYE -WebRTC_GW --> WebClient: JSON vvoipsession status\n\ +IMS_Network -> GW: BYE +GW --> WebClient: JSON vvoipsession status\n\ - status: **Released** \n\ - offer: sdp_webrtc_offer \n\ - answer: sdp_webrtc_answer_late deactivate WebClient -WebRTC_GW -> IMS_Network: 200 OK (BYE) +GW -> IMS_Network: 200 OK (BYE) IMS_Network -> RemoteEndpoint: 200 OK (BYE) end diff --git a/documentation/API_documentation/uml-diagrams/FlowsBYON-NotificationChannel.wsd b/documentation/API_documentation/uml-diagrams/FlowsBYON-NotificationChannel.wsd index 06c90ae..c8666da 100644 --- a/documentation/API_documentation/uml-diagrams/FlowsBYON-NotificationChannel.wsd +++ b/documentation/API_documentation/uml-diagrams/FlowsBYON-NotificationChannel.wsd @@ -1,6 +1,9 @@ @startuml BYON NotificationChannel 0.1.2 -title "BYON WEB RTC FLOW - Notification channel 0.1.2" +title + BYON WebRTC FLOW + Notification channel (v0.2.0) +end title autonumber "[0]"