diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index df9c728c..9fc4a90d 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -25,36 +25,46 @@ info: These endpoints allow to manage event subscription on reachability device status event. The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification. - When subscribing, it is mandatory to provide the event `type` you are subscribing to, as multiple subscription-types are managed by this API. + When subscribing, it is mandatory to provide the event `types` you are subscribing to, as multiple subscription-types are managed by this API. - Following event ``type`` are managed for this API: - - ``org.camaraproject.reachability-status-subscriptions.v0.reachability-data``: Event triggered when the device is connected to the network for Data usage. + Following event ``types`` are managed for this API: + - ``org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data``: Event triggered when the device is connected to the network for Data usage. - - ``org.camaraproject.reachability-status-subscriptions.v0.reachability-sms``: Event triggered when the device is connected to the network for SMS usage + - ``org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms``: Event triggered when the device is connected to the network for SMS usage - - ``org.camaraproject.reachability-status-subscriptions.v0.reachability-disconnected``: Event triggered when the device is not connected. + - ``org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected``: Event triggered when the device is not connected. - Note: Additionally to these list, ``org.camaraproject.reachability-status-subscriptions.v0.subscription-ends`` notification `type` is sent when the subscription ends. + Note: Additionally to these list, ``org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ends`` notification `type` is sent when the subscription ends. This notification does not require dedicated subscription. It is used in following cases: - - the subscription expire time (optionally by the requester) has been reached + - 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 API server has to stop sending notification prematurely. + - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached + - the API server has to stop sending notification prematurely ### Notifications callback - 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. + 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. - **WARNING**: This callback endpoint must be exposed and reachable on the listener side under `notificationUrl` defined in the `webhook` attribute. + _**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 reachability-status 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) - termsOfService: https://swagger.io/terms/ - contact: - email: project-email@sample.com + # Authorization and authentication + + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, 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. + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -64,7 +74,7 @@ externalDocs: url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/reachability-status-subscriptions/v0" + - url: "{apiRoot}/device-reachability-status-subscriptions/v0" variables: apiRoot: default: http://localhost:9091 @@ -86,20 +96,20 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - reachability-status:subscriptions:create + - device-reachability-status-subscriptions:org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data:create + - device-reachability-status-subscriptions:org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms:create + - device-reachability-status-subscriptions:org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected: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 any device reachability status related event occurs. @@ -113,6 +123,12 @@ paths: schema: $ref: "#/components/schemas/CloudEvent" examples: + reachability-data: + $ref: "#/components/examples/REACHABILITY_DATA" + reachability-sms: + $ref: "#/components/examples/REACHABILITY_SMS" + reachability-disconnected: + $ref: "#/components/examples/REACHABILITY_DISCONNECTED" subscription-ends: $ref: "#/components/examples/SUBSCRIPTION_ENDS" responses: @@ -127,6 +143,10 @@ paths: $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": @@ -144,7 +164,7 @@ paths: 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: @@ -155,13 +175,17 @@ paths: 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" + "422": + $ref: "#/components/responses/CreateSubscription422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -176,7 +200,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - reachability-status:subscriptions:read + - device-reachability-status-subscriptions:read responses: "200": description: List of event subscription details @@ -189,7 +213,7 @@ paths: type: array minItems: 0 items: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" "400": $ref: "#/components/responses/Generic400" "401": @@ -209,7 +233,7 @@ paths: description: Retrieve a given subscription by ID security: - openId: - - reachability-status:subscriptions:read + - device-reachability-status-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -222,9 +246,17 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" + examples: + subscription-active: + $ref: "#/components/examples/SUBSCRIPTION_ACTIVE" + subscription-activation-requested: + $ref: "#/components/examples/SUBSCRIPTION_ACTIVATION_REQUESTED" + subscription-deleted: + $ref: "#/components/examples/SUBSCRIPTION_DELETED" + "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -243,7 +275,7 @@ paths: description: Delete a given subscription by ID security: - openId: - - reachability-status:subscriptions:delete + - device-reachability-status-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -263,7 +295,7 @@ paths: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -286,7 +318,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 @@ -300,6 +332,246 @@ components: type: string schemas: + 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 + minItems: 1 + 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 subscribes to reachability SMS. If consumer sets initialEvent to true and device is already reachable by SMS, 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 + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + properties: + device: + $ref: "#/components/schemas/Device" + required: + - device + + 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: + $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" + Device: description: | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. @@ -395,58 +667,6 @@ components: type: string description: Detailed error description - CreateSubscription: - description: The request for creating a device reachability status 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: | @@ -458,10 +678,10 @@ components: subscription-ends - Event triggered when the subscription is terminated enum: - - org.camaraproject.reachability-status-subscriptions.v0.reachability-data - - org.camaraproject.reachability-status-subscriptions.v0.reachability-sms - - org.camaraproject.reachability-status-subscriptions.v0.reachability-disconnected - - org.camaraproject.reachability-status-subscriptions.v0.subscription-ends + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected + - org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ends SubscriptionEventType: type: string @@ -473,33 +693,9 @@ components: reachability-disconnected - Event triggered when the device is not connected. enum: - - org.camaraproject.reachability-status-subscriptions.v0.reachability-data - - org.camaraproject.reachability-status-subscriptions.v0.reachability-sms - - org.camaraproject.reachability-status-subscriptions.v0.reachability-disconnected - - SubscriptionInfo: - description: Represents a device reachability status 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 + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms + - org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected SubscriptionAsync: description: Response for a device reachability status operation managed asynchronously (Creation or Deletion) @@ -535,23 +731,25 @@ 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: - org.camaraproject.reachability-status-subscriptions.v0.reachability-data: "#/components/schemas/EventReachabilityData" - org.camaraproject.reachability-status-subscriptions.v0.reachability-sms: "#/components/schemas/EventReachabilitySms" - org.camaraproject.reachability-status-subscriptions.v0.reachability-disconnected: "#/components/schemas/EventReachabilityDisconnected" - org.camaraproject.reachability-status-subscriptions.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds" + org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data: "#/components/schemas/EventReachabilityData" + org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms: "#/components/schemas/EventReachabilitySms" + org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected: "#/components/schemas/EventReachabilityDisconnected" + org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds" Source: type: string @@ -569,7 +767,7 @@ components: * 1-555-123-4567 example: "https://notificationSendServer12.supertelco.com" - EventTime: + DateTime: type: string format: date-time description: | @@ -629,9 +827,8 @@ components: subscriptionId: $ref: "#/components/schemas/SubscriptionId" - SubscriptionEnds: - description: Event detail structure for org.camaraproject.reachability-status-subscriptions.v0.subscription-ends event + description: Event detail structure for org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ends event type: object required: - device @@ -648,15 +845,201 @@ components: TerminationReason: type: string description: | - NETWORK_TERMINATED - API server stopped sending notification - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - SUBSCRIPTION_DELETED - Subscription was deleted by the requester + - NETWORK_TERMINATED - API server stopped sending notification + - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached + - SUBSCRIPTION_DELETED - Subscription was deleted by the requester + - 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 enum: + - MAX_EVENTS_REACHED - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED - SUBSCRIPTION_DELETED + - ACCESS_TOKEN_EXPIRED + + 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: @@ -683,6 +1066,28 @@ 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: @@ -722,6 +1127,47 @@ 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" + 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: @@ -748,13 +1194,73 @@ 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: + REACHABILITY_DATA: + value: + id: "123656" + source: https://notificationSendServer12.supertelco.com + type: org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data + specversion: "1.0" + datacontenttype: application/json + data: + device: + phoneNumber: +123456787 + subscriptionId: qs15-h556-rt89-1298 + time: 2023-01-19T13:18:23.682Z + + REACHABILITY_SMS: + value: + id: "123656" + source: https://notificationSendServer12.supertelco.com + type: org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms + specversion: "1.0" + datacontenttype: application/json + data: + device: + phoneNumber: +123456787 + subscriptionId: qs15-h556-rt89-1298 + time: 2023-01-19T13:18:23.682Z + + REACHABILITY_DISCONNECTED: + value: + id: "123656" + source: https://notificationSendServer12.supertelco.com + type: org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected + specversion: "1.0" + datacontenttype: application/json + data: + device: + phoneNumber: +123456787 + subscriptionId: qs15-h556-rt89-1298 + time: 2023-01-19T13:18:23.682Z + SUBSCRIPTION_ENDS: value: id: "123658" source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.reachability-status-subscriptions.v0.subscription-ends + type: org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ends specversion: "1.0" datacontenttype: application/json data: @@ -763,3 +1269,57 @@ components: terminationReason: SUBSCRIPTION_EXPIRED subscriptionId: qs15-h556-rt89-1298 time: 2024-03-22T05:40:23.682Z + + SUBSCRIPTION_ACTIVE: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: ACTIVE + + SUBSCRIPTION_ACTIVATION_REQUESTED: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: ACTIVATION_REQUESTED + + SUBSCRIPTION_DELETED: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: DELETED diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml new file mode 100644 index 00000000..fb4e6054 --- /dev/null +++ b/code/API_definitions/device-reachability-status.yaml @@ -0,0 +1,546 @@ +openapi: 3.0.3 +info: + title: Device Reachability Status + description: | + This API provides the customer with the ability to query device reachability status. + + # Introduction + + ## Reachability Status + + API consumer is able to verify whether a certain user device is reachable from the network via data- or sms-usage. + + ## 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. + + * **Reachability** : Reachability status. + - `CONNECTED_SMS`, if device is connected to the network via SMS usage + - `CONNECTED_DATA`, if device is connected to the network via data usage + - `NOT_CONNECTED`, if device is not connected to the network + + * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. + + ## API Functionality + + The API exposes following capabilities: + + ### Device Reachability situation + + The endpoint `POST /retrieve` allows to get current connectivity status information synchronously. + + ## Authorization and authentication + + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, 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) + + 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}/device-reachability-status/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root +tags: + - name: Device reachability status + description: Operations to get the current reachability status of a device +paths: + /retrieve: + post: + tags: + - Device reachability status + summary: "Get the current reachability status information" + description: Get the current reachability status information + operationId: getReachabilityStatus + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - device-reachability-status:read + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RequestReachabilityStatus" + required: true + responses: + "200": + description: Contains information about current reachability status + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ReachabilityStatusResponse" + examples: + Connected-With-SMS: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + reachabilityStatus: CONNECTED_SMS + Connected-With-DATA: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + reachabilityStatus: CONNECTED_DATA + Not-Connected: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + reachabilityStatus: NOT_CONNECTED + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + 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: + LastStatusTime: + description: Last time that the associated device reachability status was updated + type: string + format: date-time + example: "2024-02-20T10:41:38.657Z" + ReachabilityStatusResponse: + type: object + required: + - reachabilityStatus + properties: + lastStatusTime: + $ref: "#/components/schemas/LastStatusTime" + reachabilityStatus: + $ref: "#/components/schemas/ReachabilityStatus" + ReachabilityStatus: + description: | + CONNECTED_DATA: The device is connected to the network for Data usage + + CONNECTED_SMS: The device is connected to the network for SMS usage + + NOT_CONNECTED: The device is not connected + type: string + enum: + - CONNECTED_DATA + - CONNECTED_SMS + - NOT_CONNECTED + 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 + + RequestReachabilityStatus: + description: The request to retrieve the current roaming-status for the requested device. + type: object + properties: + device: + $ref: "#/components/schemas/Device" + + ErrorInfo: + description: The error object used for 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 + + responses: + 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: Unauthorized + 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. + In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: + - Phone number cannot be deducted from access token context.(`{"code": "INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) + headers: + X-Correlator: + description: Correlation id for the different services + schema: + type: string + 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." + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + NOT_FOUND: + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found + DEVICE_IDENTIFIER_NOT_FOUND: + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Some identifier cannot be matched to a device + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + 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. + Generic422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + 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. + GENERIC_422_UNABLE_TO_PROVIDE_REACHABILITY_STATUS: + value: + status: 422 + code: UNABLE_TO_PROVIDE_REACHABILITY_STATUS + message: Network issue - Unable to provide reachability status + GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: + value: + status: 422 + code: UNSUPPORTED_DEVICE_IDENTIFIERS + message: None of the provided device identifiers is supported by the implementation + 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: Internal 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. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable + 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. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. diff --git a/code/API_definitions/device-roaming-status-subscriptions.yaml b/code/API_definitions/device-roaming-status-subscriptions.yaml index 9b15bdca..86bc091c 100644 --- a/code/API_definitions/device-roaming-status-subscriptions.yaml +++ b/code/API_definitions/device-roaming-status-subscriptions.yaml @@ -40,23 +40,33 @@ info: This notification does not require dedicated subscription. It is used in following cases: - - the subscription expire time (optionally by the requester) has been reached + - 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 API server has to stop sending notification prematurely. + - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached + - the API server has to stop sending notification prematurely ### Notifications callback - 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. + 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. - **WARNING**: This callback endpoint must be exposed and reachable on the listener side under `notificationUrl` defined in the `webhook` attribute. + _**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 reachability-status 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) - termsOfService: https://swagger.io/terms/ - contact: - email: project-email@sample.com + # Authorization and authentication + + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, 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. + license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html @@ -66,7 +76,7 @@ externalDocs: url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/roaming-status-subscriptions/v0" + - url: "{apiRoot}/device-roaming-status-subscriptions/v0" variables: apiRoot: default: http://localhost:9091 @@ -88,20 +98,21 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - roaming-status:subscriptions:create + - device-roaming-status-subscriptions:org.camaraproject.roaming-status-subscriptions.v0.roaming-status:create + - device-roaming-status-subscriptions:org.camaraproject.roaming-status-subscriptions.v0.roaming-on:create + - device-roaming-status-subscriptions:org.camaraproject.roaming-status-subscriptions.v0.roaming-off:create + - device-roaming-status-subscriptions:org.camaraproject.roaming-status-subscriptions.v0.roaming-change-country: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 any device roaming status related event occurs. @@ -137,6 +148,10 @@ paths: $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": @@ -154,7 +169,7 @@ paths: 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: @@ -165,13 +180,17 @@ paths: 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" + "422": + $ref: "#/components/responses/CreateSubscription422" + "429": + $ref: "#/components/responses/Generic429" "500": $ref: "#/components/responses/Generic500" "503": @@ -186,7 +205,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - roaming-status:subscriptions:read + - device-roaming-status-subscriptions:read responses: "200": description: List of event subscription details @@ -199,7 +218,7 @@ paths: type: array minItems: 0 items: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" "400": $ref: "#/components/responses/Generic400" "401": @@ -219,7 +238,7 @@ paths: description: Retrieve a given subscription by ID security: - openId: - - roaming-status:subscriptions:read + - device-roaming-status-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -232,9 +251,16 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/SubscriptionInfo" + $ref: "#/components/schemas/Subscription" + examples: + subscription-active: + $ref: "#/components/examples/SUBSCRIPTION_ACTIVE" + subscription-activation-requested: + $ref: "#/components/examples/SUBSCRIPTION_ACTIVATION_REQUESTED" + subscription-deleted: + $ref: "#/components/examples/SUBSCRIPTION_DELETED" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -253,7 +279,7 @@ paths: description: Delete a given subscription by ID security: - openId: - - roaming-status:subscriptions:delete + - device-roaming-status-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: '#/components/parameters/x-correlator' @@ -273,7 +299,7 @@ paths: schema: $ref: "#/components/schemas/SubscriptionAsync" "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/SubscriptionIdRequired" "401": $ref: "#/components/responses/Generic401" "403": @@ -296,7 +322,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 @@ -310,6 +336,246 @@ components: type: string schemas: + 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 + minItems: 1 + 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 subscribes to reachability SMS. If consumer sets initialEvent to true and device is already reachable by SMS, 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 + + SubscriptionDetail: + description: The detail of the requested event subscription + type: object + properties: + device: + $ref: "#/components/schemas/Device" + required: + - device + + 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: + $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" + Device: description: | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. @@ -415,58 +681,6 @@ components: type: string description: Detailed error description - CreateSubscription: - description: The request for creating a device roaming status 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: | @@ -502,36 +716,9 @@ components: - org.camaraproject.roaming-status-subscriptions.v0.roaming-on - org.camaraproject.roaming-status-subscriptions.v0.roaming-off - org.camaraproject.roaming-status-subscriptions.v0.roaming-change-country - - org.camaraproject.roaming-status-subscriptions.v0.connectivity-data - - org.camaraproject.roaming-status-subscriptions.v0.connectivity-sms - - org.camaraproject.roaming-status-subscriptions.v0.connectivity-disconnected - - SubscriptionInfo: - description: Represents a device roaming status 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 a device roaming status operation managed asynchronously (Creation or Deletion) + description: Response for a device reachability status operation managed asynchronously (Creation or Deletion) type: object properties: subscriptionId: @@ -728,6 +915,36 @@ components: - SUBSCRIPTION_DELETED 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: @@ -754,6 +971,26 @@ 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: @@ -793,6 +1030,47 @@ 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" + 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: @@ -819,7 +1097,28 @@ 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: ROAMING_STATUS: value: @@ -891,3 +1190,57 @@ components: terminationReason: SUBSCRIPTION_EXPIRED subscriptionId: qs15-h556-rt89-1298 time: 2023-01-19T13:18:23.682Z + + SUBSCRIPTION_ACTIVE: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.roaming-status-subscriptions.v0.roaming-on" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: ACTIVE + + SUBSCRIPTION_ACTIVATION_REQUESTED: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.roaming-status-subscriptions.v0.roaming-on" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: ACTIVATION_REQUESTED + + SUBSCRIPTION_DELETED: + value: + id: 550e8400-e29b-41d4-a716-446655440000 + sink: https://endpoint.example.com/sink + protocol: HTTP + types: + - "org.camaraproject.roaming-status-subscriptions.v0.roaming-on" + config: + subscriptionDetail: + device: + phoneNumber: "+123456789" + subscriptionExpireTime: 2024-07-17T13:18:23.682Z + subscriptionMaxEvents: 5 + initialEvent: true + startsAt: 2024-07-03T21:12:02.871Z + expiresAt: 2024-07-03T21:12:02.871Z + status: DELETED diff --git a/code/API_definitions/device-roaming-status.yaml b/code/API_definitions/device-roaming-status.yaml new file mode 100644 index 00000000..d02d395e --- /dev/null +++ b/code/API_definitions/device-roaming-status.yaml @@ -0,0 +1,572 @@ +openapi: 3.0.3 +info: + title: Device Roaming Status + description: | + This API provides the customer with the ability to query device roaming Status + + # Introduction + + ## Roaming Status + API consumer is able to verify whether a certain user device is in roaming situation (or not). + + The verification of the roaming situation depends on the network's ability. Additionally to the roaming status, when the device is in roaming situation, visited country information could be returned in the response. + + ## Possible Use-Cases + Roaming status verification could be useful in scenario such as (not exhaustive): + - For regulatory reasons, where a customer may need to be within a certain jurisdiction, or out with others, in order for transactions to be authorized + - For security / fraud reasons, to establish that a customer is located where they claim to be + - For service delivery reasons, to ensure that the customer has access to particular service, and will not incur roaming charges in accessing them + + + ## 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. + + * **Roaming** : Roaming status - `true`, if device is in roaming situation - `false` else. + + * **Country** : Country code and name - visited country information, provided if the device is in roaming situation. + + * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. + + ## API Functionality + + The API exposes following capabilities: + + ## Device roaming situation + + The endpoint `POST /retrieve` allows to get roaming status and country information (if device in roaming situation) synchronously. + + ## Authorization and authentication + + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, 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) + + 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}/device-roaming-status/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + +tags: + - name: Roaming status retrieval + description: Operation to get device roaming status and country information (if roaming) synchronously +paths: + /retrieve: + post: + tags: + - Roaming status retrieval + summary: "Get the current roaming status and the country information" + description: Get the current roaming status and the country information + operationId: getRoamingStatus + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - device-roaming-status:read + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RequestRoamingStatus" + required: true + responses: + "200": + description: Contains information about current roaming status + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/RoamingStatusResponse" + examples: + No-Country-Name: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + roaming: true + countryCode: 901 + countryName: [] + Single-Country-Code: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + roaming: true + countryCode: 262 + countryName: ["DE"] + Multiple-Country-Codes: + value: + lastStatusTime: "2024-02-20T10:41:38.657Z" + roaming: true + countryCode: 340 + countryName: ["BL", "GF", "GP", "MF", "MQ"] + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "405": + $ref: "#/components/responses/Generic405" + "406": + $ref: "#/components/responses/Generic406" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/Generic422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "502": + $ref: "#/components/responses/Generic502" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + parameters: + 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: + RoamingStatusResponse: + type: object + required: + - roaming + properties: + lastStatusTime: + $ref: "#/components/schemas/LastStatusTime" + roaming: + $ref: "#/components/schemas/ActiveRoaming" + countryCode: + $ref: "#/components/schemas/CountryCode" + countryName: + $ref: "#/components/schemas/CountryName" + + LastStatusTime: + description: Last time that the associated device roaming status was updated + type: string + format: date-time + example: "2024-02-20T10:41:38.657Z" + + ActiveRoaming: + description: Roaming status. True, if it is roaming + type: boolean + + 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 + + RequestRoamingStatus: + description: The request for retrieving the current roaming status for the requested device. + type: object + properties: + device: + $ref: "#/components/schemas/Device" + + ErrorInfo: + description: The error object used for 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 + + responses: + 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: Unauthorized + 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. + In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: + - Phone number cannot be deducted from access token context.(`{"code": "3INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) + headers: + X-Correlator: + description: Correlation id for the different services + schema: + type: string + 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." + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + NOT_FOUND: + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found + DEVICE_IDENTIFIER_NOT_FOUND: + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Some identifier cannot be matched to a device + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + 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. + + Generic422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + 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. + GENERIC_422_UNABLE_TO_PROVIDE_ROAMING_STATUS: + value: + status: 422 + code: UNABLE_TO_PROVIDE_ROAMING_STATUS + message: Network issue - Unable to provide roaming status + GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS: + value: + status: 422 + code: UNSUPPORTED_DEVICE_IDENTIFIERS + message: None of the provided device identifiers is supported by the implementation + + 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: Internal 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. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable + 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. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. diff --git a/code/API_definitions/device-status.yaml b/code/API_definitions/device-status.yaml deleted file mode 100644 index a284a8e6..00000000 --- a/code/API_definitions/device-status.yaml +++ /dev/null @@ -1,1199 +0,0 @@ -openapi: 3.0.3 -info: - title: Device Status - description: | - This API provides the customer with the ability to query device: - - Roaming Status - - Connectivity Status - - - Moreover, this API extends the functionality by allowing users customers to subscribe to events associated with these status queries. - - # Introduction - - ## Roaming Status - API consumer is able to verify whether a certain user device is in roaming situation (or not). This capability is provided in 2 ways: - - via direct request with the roaming situation in the response. - - via a subscription request - in this case the roaming situation is not in the response but event notification is sent back to the event subscriber when roaming situation has changed. - - The verification of the roaming situation depends on the network's ability. Additionally to the roaming status, when the device is in roaming situation, visited country information could be returned in the response. - - ## Connectivity Status - - API consumer is able to verify whether a certain user device is connected to the network via data- or sms-usage. This capability is provided in 2 ways: - - via direct request with the connectivity situation in the response. - - via a subscription request - in this case the connectivity situation is not in the response but event notification is sent back to the event subscriber when connectivity situation has changed. - - ## Possible Use-Cases - Device status verification could be useful in scenario such as (not exhaustive): - - For regulatory reasons, where a customer may need to be within a certain jurisdiction, or out with others, in order for transactions to be authorized - - For security / fraud reasons, to establish that a customer is located where they claim to be - - For service delivery reasons, to ensure that the customer has access to particular service, and will not incur roaming charges in accessing them - - - # 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. - - * **Roaming** : Roaming status - `true`, if device is in roaming situation - `false` else. - - * **Country** : Country code and name - visited country information, provided if the device is in roaming situation. - - * **Connectivity** : Connectivity status. - - `CONNECTED_SMS`, if device is connected to the network via SMS usage - - `CONNECTED_DATA`, if device is connected to the network via data usage - - `NOT_CONNECTED`, if device is not connected to the network - - * **LastStatusTime** : This property specifies the time when the status was last updated. Its presence in the response indicates the freshness of the information, while its absence implies the information may be outdated or its freshness is uncertain. - - # API Functionality - - The API exposes following capabilities: - - ## Device roaming situation - - The endpoint `POST /retrieve-roaming-status` allows to get roaming status and country information (if device in roaming situation) synchronously. - - ## Device connectivity situation - - The endpoint `POST /retrieve-connectivity-status` allows to get current connectivity status information synchronously. - - ## Device status subscription - - These endpoints allow to manage event subscription on roaming device status event. - The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification. - - It is mandatory in the subscription to provide the event `type` subscribed are several are managed in this API. - - Following event ``type`` are managed for this API: - - ``org.camaraproject.device-status.v0.roaming-status`` - Event triggered when the device switch from roaming ON to roaming OFF and conversely - - - ``org.camaraproject.device-status.v0.roaming-on`` - Event triggered when the device switch from roaming OFF to roaming ON - - - ``org.camaraproject.device-status.v0.roaming-off``: Event triggered when the device switch from roaming ON to roaming OFF - - - ``org.camaraproject.device-status.v0.roaming-change-country``: Event triggered when the device in roaming change country code - - - ``org.camaraproject.device-status.v0.connectivity-data``: Event triggered when the device is connected to the network for Data usage. - - - ``org.camaraproject.device-status.v0.connectivity-sms``: Event triggered when the device is connected to the network for SMS usage - - - ``org.camaraproject.device-status.v0.connectivity-disconnected``: Event triggered when the device is not connected. - - Note: Additionally to these list, ``org.camaraproject.device-status.v0.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 or if the API server has to stop sending notification prematurely. - - ### Notifications callback - - 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: http://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: 0.6.0-alpha.1 -externalDocs: - description: Product documentation at CAMARA - url: https://github.com/camaraproject/ - -servers: - - url: "{apiRoot}/device-status/v0.6alpha1" - variables: - apiRoot: - default: http://localhost:9091 - description: API root - -tags: - - name: Device connectivity status - description: Operations to get the current connectivity status of a device - - name: Device roaming status - description: Operation to get device roaming status and country information (if roaming) synchronously - - name: Device status subscription - description: Operation to manage event subscription on device status event (roaming, connectivity) - -paths: - /retrieve-connectivity-status: - post: - tags: - - Device connectivity status - summary: "Get the current connectivity status information" - description: Get the current connectivity status information - operationId: getConnectivityStatus - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - device-status:retrieve-connectivity-status:read - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/RequestConnectivityStatus" - required: true - responses: - "200": - description: Contains information about current connectivity status - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ConnectivityStatusResponse" - examples: - Connected-With-SMS: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - connectivityStatus: CONNECTED_SMS - Connected-With-DATA: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - connectivityStatus: CONNECTED_DATA - Not-Connected: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - connectivityStatus: NOT_CONNECTED - "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" - /retrieve-roaming-status: - post: - tags: - - Device roaming status - summary: "Get the current roaming status and the country information" - description: Get the current roaming status and the country information - operationId: getRoamingStatus - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - device-status:retrieve-roaming-status:read - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/RequestRoamingStatus" - required: true - responses: - "200": - description: Contains information about current roaming status - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/RoamingStatusResponse" - examples: - No-Country-Name: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - roaming: true - countryCode: 901 - countryName: [] - Single-Country-Code: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - roaming: true - countryCode: 262 - countryName: ["DE"] - Multiple-Country-Codes: - value: - lastStatusTime: "2024-02-20T10:41:38.657Z" - roaming: true - countryCode: 340 - countryName: ["BL", "GF", "GP", "MF", "MQ"] - "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" - /subscriptions: - post: - tags: - - Device status subscription - summary: "Create a device status event subscription for a device" - description: Create a device status event subscription for a device - operationId: createDeviceStatusSubscription - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - device-status: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 any device status related event occurs. - operationId: postNotification - parameters: - - $ref: '#/components/parameters/x-correlator' - requestBody: - required: true - content: - application/cloudevents+json: - schema: - $ref: "#/components/schemas/CloudEvent" - examples: - roaming-status: - $ref: "#/components/examples/ROAMING_STATUS" - roaming-change-country: - $ref: "#/components/examples/ROAMING_CHANGE_COUNTRY" - roaming-on: - $ref: "#/components/examples/ROAMING_ON" - roaming-off: - $ref: "#/components/examples/ROAMING_OFF" - connectivity-data: - $ref: "#/components/examples/CONNECTIVITY_DATA" - connectivity-sms: - $ref: "#/components/examples/CONNECTIVITY_SMS" - connectivity-disconnected: - $ref: "#/components/examples/CONNECTIVITY_DISCONNECTED" - 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: - - Device status subscription - summary: "Retrieve a list of device status event subscription" - description: Retrieve a list of device status event subscription(s) - operationId: retrieveSubscriptionList - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - device-status: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: - - Device status subscription - summary: "Retrieve a device status event subscription for a device" - operationId: retrieveSubscription - description: Retrieve a given subscription by ID - security: - - openId: - - device-status: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: - - Device status subscription - summary: "Delete a device status event subscription for a device" - operationId: deleteSubscription - description: Delete a given subscription by ID - security: - - openId: - - device-status: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: - RoamingStatusResponse: - type: object - required: - - roaming - properties: - lastStatusTime: - $ref: "#/components/schemas/LastStatusTime" - roaming: - $ref: "#/components/schemas/ActiveRoaming" - countryCode: - $ref: "#/components/schemas/CountryCode" - countryName: - $ref: "#/components/schemas/CountryName" - - LastStatusTime: - description: Last time that the associated device roaming status/connectivity was updated - type: string - format: date-time - example: "2024-02-20T10:41:38.657Z" - - ActiveRoaming: - description: Roaming status. True, if it is roaming - type: boolean - - ConnectivityStatusResponse: - type: object - required: - - connectivityStatus - properties: - lastStatusTime: - $ref: "#/components/schemas/LastStatusTime" - connectivityStatus: - $ref: "#/components/schemas/ConnectivityStatus" - - ConnectivityStatus: - description: | - CONNECTED_DATA: The device is connected to the network for Data usage - - CONNECTED_SMS: The device is connected to the network for SMS usage - - NOT_CONNECTED: The device is not connected - type: string - enum: - - CONNECTED_DATA - - CONNECTED_SMS - - NOT_CONNECTED - - 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 - - RequestRoamingStatus: - type: object - properties: - device: - $ref: "#/components/schemas/Device" - required: - - device - - RequestConnectivityStatus: - type: object - properties: - device: - $ref: "#/components/schemas/Device" - required: - - device - - 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 Status 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: | - roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely - - roaming-on - Event triggered when the device switch from roaming OFF to roaming ON - - roaming-off - Event triggered when the device switch from roaming ON to roaming OFF - - roaming-change-country - Event triggered when the device in roaming change country code - - connectivity-data - Event triggered when the device is connected to the network for Data usage. - - connectivity-sms - Event triggered when the device is connected to the network for SMS usage - - connectivity-disconnected - Event triggered when the device is not connected. - - subscription-ends - Event triggered when the subscription is terminated - enum: - - org.camaraproject.device-status.v0.roaming-status - - org.camaraproject.device-status.v0.roaming-on - - org.camaraproject.device-status.v0.roaming-off - - org.camaraproject.device-status.v0.roaming-change-country - - org.camaraproject.device-status.v0.connectivity-data - - org.camaraproject.device-status.v0.connectivity-sms - - org.camaraproject.device-status.v0.connectivity-disconnected - - org.camaraproject.device-status.v0.subscription-ends - - SubscriptionEventType: - type: string - description: | - roaming-status - Event triggered when the device switch from roaming ON to roaming OFF and conversely - - roaming-on - Event triggered when the device switch from roaming OFF to roaming ON - - roaming-off - Event triggered when the device switch from roaming ON to roaming OFF - - roaming-change-country - Event triggered when the device in roaming change country code - - connectivity-data - Event triggered when the device is connected to the network for Data usage. - - connectivity-sms - Event triggered when the device is connected to the network for SMS usage - - connectivity-disconnected - Event triggered when the device is not connected. - - enum: - - org.camaraproject.device-status.v0.roaming-status - - org.camaraproject.device-status.v0.roaming-on - - org.camaraproject.device-status.v0.roaming-off - - org.camaraproject.device-status.v0.roaming-change-country - - org.camaraproject.device-status.v0.connectivity-data - - org.camaraproject.device-status.v0.connectivity-sms - - org.camaraproject.device-status.v0.connectivity-disconnected - - SubscriptionInfo: - description: Represents a device status 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 a device status operation 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.device-status.v0.roaming-status: "#/components/schemas/EventRoamingStatus" - org.camaraproject.device-status.v0.roaming-change-country: "#/components/schemas/EventRoamingChangeCountry" - org.camaraproject.device-status.v0.roaming-off: "#/components/schemas/EventRoamingOff" - org.camaraproject.device-status.v0.roaming-on: "#/components/schemas/EventRoamingOn" - org.camaraproject.device-status.v0.connectivity-data: "#/components/schemas/EventConnectivityData" - org.camaraproject.device-status.v0.connectivity-sms: "#/components/schemas/EventConnectivitySms" - org.camaraproject.device-status.v0.connectivity-disconnected: "#/components/schemas/EventConnectivityDisconnected" - org.camaraproject.device-status.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds" - - 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" - - EventRoamingStatus: - description: event structure for roaming status change - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/RoamingStatus" - - EventRoamingOn: - description: event structure for roaming on change - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/BasicDeviceEventData" - - EventRoamingOff: - description: event structure for roaming off change - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/BasicDeviceEventData" - - EventRoamingChangeCountry: - description: event structure for roaming change country - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/RoamingChangeCountry" - - EventConnectivityData: - description: event structure for connectivity data usage - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/BasicDeviceEventData" - - EventConnectivitySms: - description: event structure for connectivity SMS usage - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/BasicDeviceEventData" - - EventConnectivityDisconnected: - description: event structure for disconnection - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/BasicDeviceEventData" - - EventSubscriptionEnds: - description: event structure for event subscription ends - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/SubscriptionEnds" - - BasicDeviceEventData: - description: Event detail structure for basic device events - type: object - required: - - device - properties: - device: - $ref: "#/components/schemas/Device" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - - RoamingStatus: - description: Event detail structure for org.camaraproject.device-status.v0.roaming-status event - type: object - required: - - device - - roaming - properties: - device: - $ref: "#/components/schemas/Device" - roaming: - type: boolean - description: Roaming status. True, if it is roaming. - countryCode: - $ref: "#/components/schemas/CountryCode" - countryName: - $ref: "#/components/schemas/CountryName" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - - RoamingChangeCountry: - description: Event detail structure for org.camaraproject.device-status.v0.roaming-on event - type: object - required: - - device - properties: - device: - $ref: "#/components/schemas/Device" - countryCode: - $ref: "#/components/schemas/CountryCode" - countryName: - $ref: "#/components/schemas/CountryName" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - - SubscriptionEnds: - description: Event detail structure for org.camaraproject.device-status.v0.subscription-ends event - type: object - required: - - device - - terminationReason - - subscriptionId - properties: - device: - $ref: "#/components/schemas/Device" - terminationReason: - $ref: "#/components/schemas/TerminationReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - TerminationReason: - type: string - description: | - NETWORK_TERMINATED - API server stopped sending notification - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - enum: - - NETWORK_TERMINATED - - SUBSCRIPTION_EXPIRED - - 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: - ROAMING_STATUS: - value: - id: "123654" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.roaming-status - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456789 - roaming: true - countryCode: 208 - countryName: FR - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-17T13:18:23.682Z - - ROAMING_OFF: - value: - id: "123655" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.roaming-off - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456788 - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-18T13:18:23.682Z - - ROAMING_ON: - value: - id: "123656" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.roaming-on - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456787 - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z - - ROAMING_CHANGE_COUNTRY: - value: - id: "123657" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.roaming-change-country - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456789 - countryCode: 214 - countryName: ["ES"] - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z - - CONNECTIVITY_DATA: - value: - id: "123656" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.connectivity-data - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456787 - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z - - CONNECTIVITY_SMS: - value: - id: "123656" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.connectivity-sms - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456787 - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z - - CONNECTIVITY_DISCONNECTED: - value: - id: "123656" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.connectivity-disconnected - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456787 - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z - - SUBSCRIPTION_ENDS: - value: - id: "123658" - source: https://notificationSendServer12.supertelco.com - type: org.camaraproject.device-status.v0.subscription-ends - specversion: "1.0" - datacontenttype: application/json - data: - device: - phoneNumber: +123456789 - terminationReason: SUBSCRIPTION_EXPIRED - subscriptionId: qs15-h556-rt89-1298 - time: 2023-01-19T13:18:23.682Z