From 294ad9244d5f58ccff6e1bf990999ced1f113d10 Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Thu, 13 Jun 2024 12:25:50 +0530 Subject: [PATCH 1/6] Add files via upload --- .../device-network-type-subscription.yaml | 695 ++++++++++++++++++ 1 file changed, 695 insertions(+) create mode 100644 code/API_definitions/device-network-type-subscription.yaml diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/device-network-type-subscription.yaml new file mode 100644 index 0000000..c191613 --- /dev/null +++ b/code/API_definitions/device-network-type-subscription.yaml @@ -0,0 +1,695 @@ +openapi: 3.0.3 +info: + title: Connected Network Type Subscriptions + description: | + This API provides the customer with the ability to subscribe to notifications on changes to the connected network type of a device. + + # Introduction + + ## Connected Network Type Subscription + API consumers can subscribe to receive notifications when the connected network type of a device changes. These notifications are delivered through CloudEvents. + + + # Relevant terms and definitions + + * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. + + * **Connected Network Type**: Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + - `4GLTE`: if device is connected to the 4G network + - `5GNSA`: if device's is connected to the 4G network but using 5G New Radio (NR) capability + - `5GSA`: if device is connected to the 5G network + - `NON3GPP4G`: if device is connected to the 4G network via WiFi network (e.g. WiFi Calling) + - `NON3GPP5G`: if device's is connected to the 5G network via WiFi network (e.g. WiFi Calling) + + # API Functionality + + The API exposes following capability: + + ## Connected Network Type Subscription Management + + These endpoints allow you to manage subscriptions for receiving notifications on changes to the connected network type of a device. + The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification. + + **Supported Event Types:** + - `org.camaraproject.connected-network-type.v0.network-type-changed`: This event is triggered when the connected network type of the device changes. + + **Notification Callbacks:** + + The `notifications` callback describes the format of event notifications and expected responses to the messages sent when the event occurs. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document. + + **WARNING**: This callback endpoint must be exposed and reachable on the listener side under `notificationUrl` defined in the `webhook` attribute. + + ## Further info and support + + (FAQs will be added in a later version of the documentation) + + termsOfService: https://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/ + +servers: + - url: "{apiRoot}/connected-network-type-subscriptions/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + +tags: + - name: Connected Network Type Subscription + description: Operations to manage subscriptions for receiving notifications on changes to the connected network type of a device. + +paths: + /subscriptions: + post: + tags: + - Connected Network Type Subscription + summary: "Create a subscription for receiving notifications on changes to the connected network type of a device" + description: Create a subscription for receiving notifications on changes to the connected network type of a device. + operationId: createConnectedNetworkTypeSubscription + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - connected-network-type:subscriptions:create + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateSubscription" + required: true + callbacks: + notifications: + "{$request.body#/webhook/notificationUrl}": + post: + tags: + - Session notifications callback + summary: "Session notifications callback" + description: | + Important: this endpoint is to be implemented by the API consumer. + The Device status server will call this endpoint whenever the connected network type of the device changes. + operationId: postNotification + parameters: + - $ref: '#/components/parameters/x-correlator' + requestBody: + required: true + content: + application/cloudevents+json: + schema: + $ref: "#/components/schemas/CloudEvent" + examples: + subscription-ends: + $ref: "#/components/examples/SUBSCRIPTION_ENDS" + 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" + "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/SubscriptionInfo" + "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/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "409": + $ref: "#/components/responses/Generic409" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + get: + tags: + - Connected Network Type Subscription + summary: "Retrieve a list of device connected network type event subscription" + description: Retrieve a list of device connected network type event subscription(s) + operationId: retrieveSubscriptionList + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - connected-network-type:subscriptions: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/SubscriptionInfo" + "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: + - Connected Network Type Subscription + summary: "Retrieve a device connected network type event subscription for a device" + operationId: retrieveSubscription + description: Retrieve a given subscription by ID + security: + - openId: + - connected-network-type:subscriptions: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/SubscriptionInfo" + "400": + $ref: "#/components/responses/Generic400" + "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: + - Connected Network Type Subscription + summary: "Delete a device connected network type event subscription for a device" + operationId: deleteSubscription + description: Delete a given subscription by ID + security: + - openId: + - connected-network-type:subscriptions:delete + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: '#/components/parameters/x-correlator' + responses: + "204": + description: event 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/Generic400" + "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 + 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: + + Device: + description: | + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + + The developer can choose to provide the below specified device identifiers: + + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 + + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" + + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + publicAddress: "84.125.93.10" + publicPort: 59765 + + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" + + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + + CountryCode: + description: The Mobile country code (MCC) as an geographic region identifier for the country and the dependent areas. + type: integer + + CountryName: + description: The ISO 3166 ALPHA-2 country-codes of mapped to mobile country code(MCC). If there is mapping of one MCC to multiple countries, then we have list of countries. If there is no mapping of MCC to any country, then an empty array [] shall be returned.. + type: array + items: + type: string + + 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 + + CreateSubscription: + description: The request for creating a device connected network type event subscription. + type: object + required: + - webhook + - subscriptionDetail + properties: + subscriptionDetail: + $ref: "#/components/schemas/SubscriptionDetail" + subscriptionExpireTime: + type: string + format: date-time + example: 2023-01-17T13:18:23.682Z + description: The date time when the status-tracking has to be terminated. + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z + webhook: + $ref: "#/components/schemas/Webhook" + + Webhook: + description: Webhook information for event channel + type: object + required: + - notificationUrl + properties: + notificationUrl: + $ref: "#/components/schemas/NotificationUrl" + notificationAuthToken: + $ref: "#/components/schemas/NotificationAuthToken" + + NotificationUrl: + type: string + example: "https://application-server.com" + description: https callback address where the event notification must be POST-ed + + NotificationAuthToken: + type: string + example: "c8974e592c2fa383d4a3960714" + description: "OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken" + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + required: + - type + - device + properties: + device: + $ref: "#/components/schemas/Device" + type: + $ref: "#/components/schemas/SubscriptionEventType" + + NotificationEventType: + type: string + description: | + network-type-changed - Event triggered when the connected network type of the device changes. + enum: + - org.camaraproject.connected-network-type.v0.network-type-changed + + SubscriptionEventType: + type: string + description: | + network-type-changed - Event triggered when the connected network type of the device changes. + + enum: + - org.camaraproject.connected-network-type.v0.network-type-changed + + SubscriptionInfo: + description: Represents a connected network type of the device subscription. + allOf: + - $ref: "#/components/schemas/CreateSubscription" + - type: object + properties: + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + startsAt: + type: string + format: date-time + description: The date time when the subscription started. + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) + expiresAt: + type: string + format: date-time + description: The date time when the subscription will expire or expired. + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) + required: + - subscriptionId + - type + + SubscriptionAsync: + description: Response for changes to the connected network type of a device managed asynchronously (Creation or Deletion) + type: object + properties: + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + + SubscriptionId: + type: string + format: uuid + description: Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server + example: 550e8400-e29b-41d4-a716-446655440000 + + CloudEvent: + description: The notification callback + required: + - id + - source + - specversion + - type + - time + - data + properties: + id: + type: string + description: identifier of this event, that must be unique in the source context. + example: sd5e-uy52-88t4-za66 + source: + $ref: "#/components/schemas/Source" + type: + $ref: "#/components/schemas/NotificationEventType" + 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) + example: "1.0" + datacontenttype: + type: string + description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' + example: application/json + data: + type: object + description: Event details payload described in each CAMARA API and referenced by its type + time: + $ref: "#/components/schemas/EventTime" + discriminator: + propertyName: "type" + mapping: + org.camaraproject.connected-network-type.v0.network-type-changed: "#/components/schemas/EventNetworkTypeChange" + + Source: + type: string + format: uri-reference + minLength: 1 + description: | + Identifies the context in which an event happened, as 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" + + EventTime: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. + If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, + however all producers for the same source MUST be consistent in this respect. In other words, + either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) + example: "2018-04-05T17:31:00Z" + + + EventNetworkTypeChange: + description: event structure for network type change + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/BasicDeviceEventData" + + BasicDeviceEventData: + description: Event detail structure for basic device events + type: object + required: + - device + properties: + device: + $ref: "#/components/schemas/Device" + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + + + responses: + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + 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" + example: + status: 401 + code: "UNAUTHENTICATED" + message: "Request not authenticated due to missing, invalid, or expired credentials" + Generic403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 403 + code: "PERMISSION_DENIED" + message: "Client does not have sufficient permissions to perform this action" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + 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" + example: + status: 409 + code: CONFLICT + message: "The specified resource is in a conflict" + Generic500: + description: Server error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: "INTERNAL" + message: "Server error" + 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" + example: + status: 503 + code: "UNAVAILABLE" + message: "Service unavailable" + + examples: + NETWORK_TYPE_CHANGED: + value: + id: "123658" + source: https://notificationSendServer12.supertelco.com + type: org.camaraproject.connected-network-type.v0.network-type-changed + specversion: "1.0" + datacontenttype: application/json + data: + device: + phoneNumber: +123456789 + subscriptionId: qs15-h556-rt89-1298 + time: 2024-03-22T05:40:23.682Z From 89ab4950d8916d531f18ddc21f58c824db464df9 Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Mon, 17 Jun 2024 12:09:05 +0530 Subject: [PATCH 2/6] Update device-network-type-subscription.yaml Review comments added --- .../device-network-type-subscription.yaml | 39 ++++++++++++++----- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/device-network-type-subscription.yaml index c191613..cb5718b 100644 --- a/code/API_definitions/device-network-type-subscription.yaml +++ b/code/API_definitions/device-network-type-subscription.yaml @@ -16,6 +16,8 @@ info: At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. * **Connected Network Type**: Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + - `2G`: if device is connected to the 2G network + - `3G`: if device is connected to the 3G network - `4GLTE`: if device is connected to the 4G network - `5GNSA`: if device's is connected to the 4G network but using 5G New Radio (NR) capability - `5GSA`: if device is connected to the 5G network @@ -32,7 +34,7 @@ info: The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification. **Supported Event Types:** - - `org.camaraproject.connected-network-type.v0.network-type-changed`: This event is triggered when the connected network type of the device changes. + - `org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed`: This event is triggered when the connected network type of the device changes. **Notification Callbacks:** @@ -105,8 +107,8 @@ paths: schema: $ref: "#/components/schemas/CloudEvent" examples: - subscription-ends: - $ref: "#/components/examples/SUBSCRIPTION_ENDS" + network-type-changed: + $ref: "#/components/examples/NETWORK_TYPE_CHANGED" responses: "204": description: Successful notification @@ -437,6 +439,18 @@ components: example: "c8974e592c2fa383d4a3960714" description: "OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken" + ConnectedNetworkType: + type: string + description: Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + enum: + - 2G + - 3G + - 4GLTE + - 5GNSA + - 5GSA + - NON3GPP4G + - NON3GPP5G + SubscriptionDetail: description: The detail of the requested event subscription type: object @@ -454,7 +468,7 @@ components: description: | network-type-changed - Event triggered when the connected network type of the device changes. enum: - - org.camaraproject.connected-network-type.v0.network-type-changed + - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed SubscriptionEventType: type: string @@ -462,7 +476,7 @@ components: network-type-changed - Event triggered when the connected network type of the device changes. enum: - - org.camaraproject.connected-network-type.v0.network-type-changed + - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed SubscriptionInfo: description: Represents a connected network type of the device subscription. @@ -535,7 +549,7 @@ components: discriminator: propertyName: "type" mapping: - org.camaraproject.connected-network-type.v0.network-type-changed: "#/components/schemas/EventNetworkTypeChange" + org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed: "#/components/schemas/EventNetworkTypeChange" Source: type: string @@ -573,16 +587,20 @@ components: - type: object properties: data: - $ref: "#/components/schemas/BasicDeviceEventData" + $ref: "#/components/schemas/EventNetworkTypeChangeData" - BasicDeviceEventData: - description: Event detail structure for basic device events + EventNetworkTypeChangeData: + description: Event detail structure for network type changed data events type: object required: - device + - ConnectedNetworkType + - SubscriptionId properties: device: $ref: "#/components/schemas/Device" + connectedNetworkType: + $ref: "#/components/schemas/ConnectedNetworkType" subscriptionId: $ref: "#/components/schemas/SubscriptionId" @@ -685,11 +703,12 @@ components: value: id: "123658" source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.connected-network-type.v0.network-type-changed + type: org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed specversion: "1.0" datacontenttype: application/json data: device: phoneNumber: +123456789 + ConnectedNetworkType: 5GNSA subscriptionId: qs15-h556-rt89-1298 time: 2024-03-22T05:40:23.682Z From f387b0748a394d7273eca0efef8f7bb672296e7f Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Mon, 17 Jun 2024 15:58:54 +0530 Subject: [PATCH 3/6] Review comments updated --- .../device-network-type-subscription.yaml | 879 +++++++++++++----- 1 file changed, 658 insertions(+), 221 deletions(-) diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/device-network-type-subscription.yaml index cb5718b..6cb822d 100644 --- a/code/API_definitions/device-network-type-subscription.yaml +++ b/code/API_definitions/device-network-type-subscription.yaml @@ -9,7 +9,6 @@ info: ## Connected Network Type Subscription API consumers can subscribe to receive notifications when the connected network type of a device changes. These notifications are delivered through CloudEvents. - # Relevant terms and definitions * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. @@ -26,23 +25,33 @@ info: # API Functionality - The API exposes following capability: + The API exposes following capabilities: ## Connected Network Type Subscription Management These endpoints allow you to manage subscriptions for receiving notifications on changes to the connected network type of a device. The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification. - **Supported Event Types:** - - `org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed`: This event is triggered when the connected network type of the device changes. - - **Notification Callbacks:** + It is mandatory in the subscription to provide the event `type` for which the client would like to subscribe. + + Following event ``type`` are managed for this API: + - ``org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed``: This event is triggered when the connected network type of the device changes. + + - ``org.camaraproject.geofencing-subscriptions.v0.area-left`` - Event triggered when the device leaves the given area + + + - The `notifications` callback describes the format of event notifications and expected responses to the messages sent when the event occurs. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document. + ### Notification callback - **WARNING**: This callback endpoint must be exposed and reachable on the listener side under `notificationUrl` defined in the `webhook` attribute. + This endpoint describes the event notification received on subscription listener side when the event occurred. + As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document. - ## Further info and support + _**WARNING**: This callback endpoint must be exposed on the consumer side as `POST /{$request.body#/sink}`. + Developers may provide a callback URL on which notifications regarding geofencing can be received from the service provider. + If an event occurs the application will send events to the provided webhook - 'sink'._ + + # Further info and support (FAQs will be added in a later version of the documentation) @@ -54,7 +63,7 @@ info: url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip externalDocs: - description: Product documentation at CAMARA + description: Product documentation at Camara url: https://github.com/camaraproject/ servers: @@ -75,31 +84,29 @@ paths: - Connected Network Type Subscription summary: "Create a subscription for receiving notifications on changes to the connected network type of a device" description: Create a subscription for receiving notifications on changes to the connected network type of a device. - operationId: createConnectedNetworkTypeSubscription + operationId: createSubscription parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" security: - openId: - - connected-network-type:subscriptions:create + - connected-network-type-subscriptions:org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed:create requestBody: content: application/json: schema: - $ref: "#/components/schemas/CreateSubscription" + $ref: "#/components/schemas/SubscriptionRequest" required: true callbacks: notifications: - "{$request.body#/webhook/notificationUrl}": + "{$request.body#/sink}": post: - tags: - - Session notifications callback - summary: "Session notifications callback" + summary: "notifications callback" description: | Important: this endpoint is to be implemented by the API consumer. The Device status server will call this endpoint whenever the connected network type of the device changes. operationId: postNotification parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" requestBody: required: true content: @@ -114,13 +121,17 @@ paths: description: Successful notification headers: x-correlator: - $ref: '#/components/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": @@ -128,34 +139,39 @@ paths: security: - {} - notificationsBearerAuth: [] - responses: "201": - description: Created + description: Created (Successful creation of subscription) headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/SubscriptionInfo" + $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' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/CreateSubscriptionBadRequest400" "401": $ref: "#/components/responses/Generic401" "403": - $ref: "#/components/responses/Generic403" + $ref: "#/components/responses/CreateSubscription403" "409": $ref: "#/components/responses/Generic409" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/CreateSubscription422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -165,25 +181,25 @@ paths: - Connected Network Type Subscription summary: "Retrieve a list of device connected network type event subscription" description: Retrieve a list of device connected network type event subscription(s) - operationId: retrieveSubscriptionList + operationId: retrieveConnectedNetworkTypeSubscriptionList parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" security: - openId: - - connected-network-type:subscriptions:read + - connected-network-type-subscriptions:read responses: "200": description: List of event subscription details headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: type: array minItems: 0 items: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" "400": $ref: "#/components/responses/Generic400" "401": @@ -199,26 +215,26 @@ paths: tags: - Connected Network Type Subscription summary: "Retrieve a device connected network type event subscription for a device" - operationId: retrieveSubscription - description: Retrieve a given subscription by ID + description: retrieve ConnectedNetworkType subscription information for a given subscription ID. + operationId: retrieveConnectedNetworkTypeSubscription security: - openId: - - connected-network-type:subscriptions:read + - connected-network-type-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" responses: "200": description: OK headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -232,32 +248,32 @@ paths: delete: tags: - Connected Network Type Subscription - summary: "Delete a device connected network type event subscription for a device" - operationId: deleteSubscription - description: Delete a given subscription by ID + summary: "Delete connected network type event subscription for a device" + operationId: deleteConnectedNetworkTypeSubscription + description: delete a given ConnectedNetworkType subscription. security: - openId: - - connected-network-type:subscriptions:delete + - connected-network-type-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - - $ref: '#/components/parameters/x-correlator' + - $ref: "#/components/parameters/x-correlator" responses: "204": - description: event subscription deleted + description: ConnectedNetworkType subscription deleted headers: x-correlator: - $ref: '#/components/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' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -280,7 +296,7 @@ components: description: Subscription identifier that was obtained from the create event subscription operation required: true schema: - $ref: '#/components/schemas/SubscriptionId' + $ref: "#/components/schemas/SubscriptionId" x-correlator: name: x-correlator in: header @@ -293,6 +309,300 @@ components: schema: type: string schemas: + ErrorInfo: + description: The error info object for possible error cases + 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: + allOf: + - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. + - $ref: "#/components/schemas/SinkCredential" + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: As of now we enforce to have only event type per subscription. + type: array + maxItems: 1 + items: + $ref: "#/components/schemas/SubscriptionEventType" + 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/SubscriptionDetail" + 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. + 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. + 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 area entered event. If consumer sets initialEvent to true and device is already in the geofence, an event is triggered + + SinkCredential: + 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 + + ConnectedNetworkType: + type: string + description: Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. + enum: + - 2G + - 3G + - 4GLTE + - 5GNSA + - 5GSA + - NON3GPP4G + - NON3GPP5G + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + properties: + device: + $ref: "#/components/schemas/Device" + required: + - device + + SubscriptionEventType: + type: string + description: | + network-type-changed - Event triggered when the connected network type of the device changes. + + enum: + - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed + + NotificationEventType: + type: string + description: | + network-type-changed - Event triggered when the connected network type of the device changes. + enum: + - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed + + Subscription: + description: Represents a event-type subscription. + type: object + required: + - sink + - protocol + - config + - types + - id + - startsAt + 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. + type: array + items: + type: string + config: + $ref: "#/components/schemas/Config" + id: + 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: "1119920371" + 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. + - `DEACTIVE`: 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 + - DEACTIVE + - 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 Device: description: | @@ -372,149 +682,6 @@ components: format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - CountryCode: - description: The Mobile country code (MCC) as an geographic region identifier for the country and the dependent areas. - type: integer - - CountryName: - description: The ISO 3166 ALPHA-2 country-codes of mapped to mobile country code(MCC). If there is mapping of one MCC to multiple countries, then we have list of countries. If there is no mapping of MCC to any country, then an empty array [] shall be returned.. - type: array - items: - type: string - - 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 - - CreateSubscription: - description: The request for creating a device connected network type event subscription. - type: object - required: - - webhook - - subscriptionDetail - properties: - subscriptionDetail: - $ref: "#/components/schemas/SubscriptionDetail" - subscriptionExpireTime: - type: string - format: date-time - example: 2023-01-17T13:18:23.682Z - description: The date time when the status-tracking has to be terminated. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z - webhook: - $ref: "#/components/schemas/Webhook" - - Webhook: - description: Webhook information for event channel - type: object - required: - - notificationUrl - properties: - notificationUrl: - $ref: "#/components/schemas/NotificationUrl" - notificationAuthToken: - $ref: "#/components/schemas/NotificationAuthToken" - - NotificationUrl: - type: string - example: "https://application-server.com" - description: https callback address where the event notification must be POST-ed - - NotificationAuthToken: - type: string - example: "c8974e592c2fa383d4a3960714" - description: "OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken" - - ConnectedNetworkType: - type: string - description: Network Type is intended to provide insight to connected network's capabilities from standards perspective. Actual network capabilities may differ based on implementation and MUST be checked with the connected network provider. - enum: - - 2G - - 3G - - 4GLTE - - 5GNSA - - 5GSA - - NON3GPP4G - - NON3GPP5G - - SubscriptionDetail: - description: The detail of the requested event subscription - type: object - required: - - type - - device - properties: - device: - $ref: "#/components/schemas/Device" - type: - $ref: "#/components/schemas/SubscriptionEventType" - - NotificationEventType: - type: string - description: | - network-type-changed - Event triggered when the connected network type of the device changes. - enum: - - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed - - SubscriptionEventType: - type: string - description: | - network-type-changed - Event triggered when the connected network type of the device changes. - - enum: - - org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed - - SubscriptionInfo: - description: Represents a connected network type of the device subscription. - allOf: - - $ref: "#/components/schemas/CreateSubscription" - - type: object - properties: - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - startsAt: - type: string - format: date-time - description: The date time when the subscription started. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) - expiresAt: - type: string - format: date-time - description: The date time when the subscription will expire or expired. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) - required: - - subscriptionId - - type - - SubscriptionAsync: - description: Response for changes to the connected network type of a device managed asynchronously (Creation or Deletion) - type: object - properties: - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - - SubscriptionId: - type: string - format: uuid - description: Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server - example: 550e8400-e29b-41d4-a716-446655440000 - CloudEvent: description: The notification callback required: @@ -523,12 +690,10 @@ components: - specversion - type - time - - data properties: id: type: string description: identifier of this event, that must be unique in the source context. - example: sd5e-uy52-88t4-za66 source: $ref: "#/components/schemas/Source" type: @@ -536,16 +701,18 @@ components: 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) - example: "1.0" + enum: + - "1.0" datacontenttype: type: string description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs' - example: application/json + enum: + - application/json data: type: object description: Event details payload described in each CAMARA API and referenced by its type time: - $ref: "#/components/schemas/EventTime" + $ref: "#/components/schemas/DateTime" discriminator: propertyName: "type" mapping: @@ -556,7 +723,7 @@ components: format: uri-reference minLength: 1 description: | - Identifies the context in which an event happened, as a non-empty `URI-reference` like: + 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 @@ -567,19 +734,12 @@ components: * 1-555-123-4567 example: "https://notificationSendServer12.supertelco.com" - EventTime: + DateTime: type: string format: date-time - description: | - Timestamp of when the occurrence happened. - If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer, - however all producers for the same source MUST be consistent in this respect. In other words, - either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) + description: Timestamp of when the occurrence happened. Must adhere to RFC 3339. example: "2018-04-05T17:31:00Z" - EventNetworkTypeChange: description: event structure for network type change allOf: @@ -594,8 +754,8 @@ components: type: object required: - device - - ConnectedNetworkType - - SubscriptionId + - connectedNetworkType + - subscriptionId properties: device: $ref: "#/components/schemas/Device" @@ -604,13 +764,193 @@ components: subscriptionId: $ref: "#/components/schemas/SubscriptionId" + 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: + InvalidArgument: + value: + status: 400 + code: "INVALID_ARGUMENT" + message: "Client specified an invalid argument, request body or query param" + InvalidProtocol: + value: + status: 400 + code: "INVALID_PROTOCOL" + message: "Only HTTP is supported" + InvalidCredential: + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + InvalidToken: + 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' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -623,7 +963,7 @@ components: description: Authentication problem with the client request headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -632,11 +972,32 @@ components: status: 401 code: "UNAUTHENTICATED" message: "Request not authenticated due to missing, invalid, or expired credentials" + + CreateSubscription403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PermissionDenied: + value: + status: 403 + code: "PERMISSION_DENIED" + message: "Client does not have sufficient permissions to perform this action" + TokenMismatch: + value: + status: 403 + code: "SUBSCRIPTION_MISMATCH" + message: "Inconsistent access token for requested events subscription" Generic403: description: Client does not have sufficient permission headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -649,7 +1010,7 @@ components: description: Resource Not Found headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -662,7 +1023,7 @@ components: description: Conflict headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -671,11 +1032,65 @@ components: status: 409 code: CONFLICT message: "The specified resource is in a conflict" + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 410 + code: GONE + message: "The specified resource is no longer available at the requested address" + Generic415: + description: Unsupported Media Type + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: "The specified media type is not supported" + CreateSubscription422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + PermissionDenied: + value: + status: 422 + code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" + message: "Multi event types subscription not managed" + Generic429: + description: Too Many Requests + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 429 + code: TOO_MANY_REQUESTS + message: "Endpoint does not support as many requests per time slot" Generic500: description: Server error headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -688,7 +1103,7 @@ components: description: Service unavailable. Typically the server is down. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: @@ -697,18 +1112,40 @@ components: 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" examples: NETWORK_TYPE_CHANGED: + description: The cloud event when a connected network type changed value: - id: "123658" + id: "123655" source: https://notificationSendServer12.supertelco.com type: org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed specversion: "1.0" datacontenttype: application/json data: + subscriptionId: 987654321 device: phoneNumber: +123456789 - ConnectedNetworkType: 5GNSA - subscriptionId: qs15-h556-rt89-1298 - time: 2024-03-22T05:40:23.682Z + ConnectedNetworkType: 5GNSA + time: 2023-03-22T05:40:23.682Z From 5f47f6a98c28ea2827c529f67105effc17dbbd9e Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Mon, 17 Jun 2024 17:54:48 +0530 Subject: [PATCH 4/6] Updated review comments --- .../API_definitions/device-network-type-subscription.yaml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/device-network-type-subscription.yaml index 6cb822d..4f3ffd9 100644 --- a/code/API_definitions/device-network-type-subscription.yaml +++ b/code/API_definitions/device-network-type-subscription.yaml @@ -352,6 +352,7 @@ components: Camara Event types eligible to be delivered by this subscription. Note: As of now we enforce to have only event type per subscription. type: array + minItems: 1 maxItems: 1 items: $ref: "#/components/schemas/SubscriptionEventType" @@ -573,14 +574,14 @@ components: 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. - - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted. + - `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 - - DEACTIVE + - INACTIVE - DELETED discriminator: propertyName: protocol @@ -689,6 +690,7 @@ components: - source - specversion - type + - data - time properties: id: @@ -1147,5 +1149,5 @@ components: subscriptionId: 987654321 device: phoneNumber: +123456789 - ConnectedNetworkType: 5GNSA + connectedNetworkType: 5GNSA time: 2023-03-22T05:40:23.682Z From d9a06df606faaa9bc4af112c856c3e4901488262 Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Tue, 18 Jun 2024 12:04:30 +0530 Subject: [PATCH 5/6] Updating review comments --- code/API_definitions/device-network-type-subscription.yaml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/device-network-type-subscription.yaml index 4f3ffd9..2ec102a 100644 --- a/code/API_definitions/device-network-type-subscription.yaml +++ b/code/API_definitions/device-network-type-subscription.yaml @@ -37,9 +37,6 @@ info: Following event ``type`` are managed for this API: - ``org.camaraproject.connected-network-type-subscriptions.v0.network-type-changed``: This event is triggered when the connected network type of the device changes. - - ``org.camaraproject.geofencing-subscriptions.v0.area-left`` - Event triggered when the device leaves the given area - - ### Notification callback @@ -48,7 +45,7 @@ info: As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document. _**WARNING**: This callback endpoint must be exposed on the consumer side as `POST /{$request.body#/sink}`. - Developers may provide a callback URL on which notifications regarding geofencing can be received from the service provider. + Developers may provide a callback URL on which notifications regarding connected network type can be received from the service provider. If an event occurs the application will send events to the provided webhook - 'sink'._ # Further info and support From a8456afa96710aab82c20e307eba0b39c99cff89 Mon Sep 17 00:00:00 2001 From: VijayKesharwani <122533719+VijayKesharwani@users.noreply.github.com> Date: Tue, 18 Jun 2024 12:09:35 +0530 Subject: [PATCH 6/6] Update and rename device-network-type-subscription.yaml to connected-network-type-subscriptions.yaml correcting the file name and making it plural --- ...ubscription.yaml => connected-network-type-subscriptions.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename code/API_definitions/{device-network-type-subscription.yaml => connected-network-type-subscriptions.yaml} (100%) diff --git a/code/API_definitions/device-network-type-subscription.yaml b/code/API_definitions/connected-network-type-subscriptions.yaml similarity index 100% rename from code/API_definitions/device-network-type-subscription.yaml rename to code/API_definitions/connected-network-type-subscriptions.yaml