From 09241596ab35b17573cdfd0abed42344b6475e0b Mon Sep 17 00:00:00 2001 From: Ludovic Robert <30499179+bigludo7@users.noreply.github.com> Date: Wed, 3 Jul 2024 12:12:35 +0200 Subject: [PATCH] Add files via upload --- code/API_definitions/device-status.yaml | 1199 +++++++++++++++++++++++ 1 file changed, 1199 insertions(+) create mode 100644 code/API_definitions/device-status.yaml diff --git a/code/API_definitions/device-status.yaml b/code/API_definitions/device-status.yaml new file mode 100644 index 0000000..a284a8e --- /dev/null +++ b/code/API_definitions/device-status.yaml @@ -0,0 +1,1199 @@ +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