diff --git a/code/API_definitions/device-roaming-status-subscriptions.yaml b/code/API_definitions/device-roaming-status-subscriptions.yaml index 8c9312a..60a0a9c 100644 --- a/code/API_definitions/device-roaming-status-subscriptions.yaml +++ b/code/API_definitions/device-roaming-status-subscriptions.yaml @@ -2,100 +2,96 @@ openapi: 3.0.3 info: title: Device Roaming Status Subscriptions description: | - This API provides the API consumer with the ability to subscribe to Roaming status events. + This API provides the API consumer with the ability to subscribe to roaming status events. # Introduction - ## Roaming Status - API consumer is able to be notified whether the roaming status of a certain user device has changed. - This capability is provided 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. + API consumer is able to be notified whether the roaming status of a certain user device has changed. This capability is requested via a subscription request - in this case the roaming status is not contained in the API response, but instead an event notification is sent back to the event subscriber whenever the roaming situation changes. # Relevant terms and definitions - * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + * **Roaming**:\ + For the purposes of this API, a device is considered to be roaming if it is connected to a mobile network with a different mobile country code (MCC) to its home network. A device is not considered to be roaming if it is connected to a mobile network that has the same MCC as the home network, even if that network is not the home network. Where the home network has a MCC for a country that has been allocated more than one MCC, a device is not considered to be roaming if it is connected to any network that uses a MCC for that country. - At least one identifier for the device out of four options must be provided: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. Where more than one device identifier is provided, only one identifier will be selected by the implementation and this choice indicated to the API consumer in the subscription creation response. + * **Device**:\ + A device refers to any physical entity that can connect to a network and participate in network communication. - Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. + At least one identifier for the device out of four options must be provided: IPv4 address, IPv6 address, phone number, or network access identifier assigned by the mobile network operator for the device. Where more than one device identifier is provided, only one identifier will be selected by the implementation and this choice indicated to the API consumer in the subscription creation response. - # API Functionality - - The API exposes following capability: + Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. - ## Device roaming status subscription + * **Country**:\ + The mobile country code and associated ISO country name. The visited country information is provided when the device is roaming. When the device is not roaming, the country will be that of the home network for the device, but this information is not provided by the API. - 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. + # API Functionality - When subscribing, it is mandatory to provide the event `type` you are subscribing to, as multiple subscription-types are managed by this API. + The API exposes following capability: - Following event ``type`` are managed for this API: - - ``org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status`` - Event triggered when the device switch from roaming ON to roaming OFF and conversely + ## Device Roaming Status Subscription - - ``org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on`` - Event triggered when the device switch from roaming OFF to roaming ON + These endpoints allow the API consumer to manage event subscriptions for device roaming status events. + The CAMARA subscription model is detailed in the `CAMARA API Event Subscription and Notification Guide` and uses notifications that follow the CloudEvents specification. - - ``org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off``: Event triggered when the device switch from roaming ON to roaming OFF + When creating a subscription, it is mandatory to provide the event type you are subscribing to, as multiple subscription-types are managed by this API. - - ``org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country``: Event triggered when the device in roaming change country code + Following event types are defined for this API: + - `org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status` is sent when the device roaming status changes (either starting or stopping roaming) + - `org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on` is sent when the device roaming status changes to roaming ON + - `org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off` is sent when the device roaming status changes to roaming OFF + - `org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country` is sent whenever the device remains roaming but there is a change in country name Note: Additionally, the following events could be sent, which do not require a dedicated subscription: - `org.camaraproject.device-roaming-status-subscriptions.v0.subscription-started` is sent when the subscription starts. - `org.camaraproject.device-roaming-status-subscriptions.v0.subscription-updated` is sent when the subscription is updated. - `org.camaraproject.device-roaming-status-subscriptions.v0.subscription-ended` is sent when the subscription ends. - It is used in following cases: - - the subscription expire time (optionally set by the requester) has been reached - - the maximum number of subscription events (optionally set by the requester) has been reached - - the subscription was deleted by the requester - - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached - - the API server has to stop sending notification prematurely + The `subscription-ended` event may be used in following cases: + - the subscription expire time (optionally set by the API consumer) has been reached + - the maximum number of subscription events (optionally set by the API consumer) has been reached + - the subscription was deleted by the API consumer + - the access token `sinkCredential` (optionally set by the API Consumer) expiration time has been reached + - the API provider has to stop sending notification prematurely - **Note on combined usage of ``initialEvent`` and ``subscriptionMaxEvents``**: + **Note on combined usage of `initialEvent` and `subscriptionMaxEvents`**:\ + If an event is triggered because `initialEvent` set to `true`, this event will be counted towards `subscriptionMaxEvents` if that has been specified - If an event is triggered following ``initialEvent`` set to true, - this event will be counted towards ``subscriptionMaxEvents`` (if provided). + **Clarification on `initialEvent` & `event-type` behaviour:**\ + Following table illustrate behaviour regarding event triggering depending on the **initial** roaming state of the device: - **Clarification on ``initialEvent`` & ``event-type`` behaviour:** + | subscribed event-type | device roaming status at subscription time | event sent if `initialEvent` set to `true` | + | ---------------------- | ------------------------------------------ | ------------------------------------------ | + | roaming-status | Roaming | Yes | + | roaming-status | Not roaming | Yes | + | roaming-on | Roaming | Yes | + | roaming-on | Not roaming | No | + | roaming-off | Roaming | No | + | roaming-off | Not roaming | Yes | + | roaming-change-country | Not roaming | No(*) | + | roaming-change-country | Roaming | No(*) | - Following table illustrate behaviour regarding event triggering depending on **initial** roaming state of the device: + (*) Setting `initialEvent` to `true` does not generate any inital even for the `roaming-change-country` event type. - | subscribed event-type | device roaming status at subscription time | event sent if ``initialEvent`` set to true | - | ----------------------| ------------- | --------------- | - | roaming-status | Roaming On | Yes | - | roaming-status | Roaming Off | Yes | - | roaming-on | Roaming On | Yes | - | roaming-on | Roaming Off | No | - | roaming-off | Roaming On | No | - | roaming-off | Roaming Off | Yes | - | roaming-change-country | Roaming Off | No(*) | - | roaming-change-country | Roaming On | No(*) | - - (*) Use of ``initialEvent`` has no impact on roaming-change-country event-type. - - **Clarification on ``roaming-change-country`` event-type:** - - ``roaming-change-country`` event is sent only when the device stays in roaming situation and change country. - Suppose a device from Germany & all event types subscribed: + **Clarification on the `roaming-change-country` event type:**\ + The `roaming-change-country` event is sent only when the device is roaming and remains roaming following a change in country name. + For example, if a device has a home network in Germany and all event types are subscribed to:\ - Device moves from Germany to France: - - triggered: roaming-status & roaming-on - - not triggered: roaming-change-country & roaming-off - - Device moves from France to Belgium: - - triggered: roaming-change-country - - not triggered: roaming-status, roaming-on & roaming-off - - Device moves from Belgium back to Germany - - triggered: roaming-status & roaming-off - - not triggered: roaming-on & roaming-change-country - + - triggered: `roaming-status` & `roaming-on` + - not triggered: `roaming-change-country` & `roaming-off` + - Device then moves from France to Belgium: + - triggered: `roaming-change-country` + - not triggered: `roaming-status`, `roaming-on` & `roaming-off` + - Device then moves from Belgium back to Germany + - triggered: `roaming-status` & `roaming-off` + - not triggered: `roaming-on` & `roaming-change-country` ### Notifications callback - 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. + This endpoint describes the format of the event notification received by the API consumer when an event is sent. + A detailed description of the event subscription and notification mechanism is provided in the `CAMARA API Event Subscription and Notification Guide`. - _**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`._ + _**WARNING**:\ + API consumers may optionally provide a callback URL on which reachability status notifications from the API provider can be received. This callback endpoint must be exposed by API consumer as `POST /{$request.body#/sink}`. When an event occurs, the API provider will send the event to the URI specified by `sink`._ @@ -143,7 +139,7 @@ info: The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. diff --git a/code/API_definitions/device-roaming-status.yaml b/code/API_definitions/device-roaming-status.yaml index ac720c2..c33e8d8 100644 --- a/code/API_definitions/device-roaming-status.yaml +++ b/code/API_definitions/device-roaming-status.yaml @@ -19,25 +19,80 @@ info: ## Relevant terms and definitions - * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + * **Roaming**:\ + For the purposes of this API, a device is considered to be roaming if it is connected to a mobile network with a different mobile country code (MCC) to its home network. A device is not considered to be roaming if it is connected to a mobile network that has the same MCC as the home network, even if that network is not the home network. Where a country has been allocated more than one MCC, a device is not considered to be roaming if it is connected to any network that uses a MCC allocated for that country, even if that MCC is different to that of the home network. - At least one identifier for the device (user equipment) out of four options must be provided: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. Where more than one device identifier is provided, only one identifier will be selected by the implementation and this choice indicated to the API consumer in the session creation response. + * **Device**:\ + A device refers to any physical hardware that can connect to a mobile network and participate in network communication. - Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. + At least one identifier for the device (user equipment) out of four options must be provided: IPv4 address, IPv6 address, phone number, or network access identifier assigned by the mobile network operator for the device. Where more than one device identifier is provided, only one identifier will be selected by the implementation and this choice indicated to the API consumer in the response together with the roaming status. - * **Roaming** : Roaming status - `true`, if device is in roaming situation - `false` else. + Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. - * **Country** : Country code and name - visited country information, provided if the device is in roaming situation. + * **Country**:\ + The mobile country code and associated ISO country name. The visited country information is provided when the device is roaming. When the device is not roaming, the country will be that of the home network for the device, but this information is not provided by the API. - * **LastStatusTime** : The time when the status was last confirmed to be correct. An older status is more likely to now be incorrect. + * **Last Status Time**:\ + The time when the roaming status was last confirmed to be correct by the API provider. An older status is more likely to now be incorrect. The API provider may be unable to confirm a more recent status because, for example, the device may no longer be connected to the mobile network. # API Functionality The API exposes following capabilities: - ## Device roaming situation + ## Device Roaming Status - The endpoint `POST /retrieve` allows to get roaming status and country information (if device in roaming situation) synchronously. + The endpoint `POST /retrieve` allows the API consumer to synchronously get the roaming status and country information (when roaming) for a specific device + + An example of a JSON response object is as follows: + ``` + { + "lastStatusTime": "2024-02-20T10:41:38.657Z", + "roaming": true, + "countryCode": 262, + "countryName": [ + "DE" + ] + } + ``` + + ## Error Handling + Errors may be returned for the following reasons. Note that this list is not exhaustive. + + `401 UNAUTHENTICATED`: + - The access token is not a valid access token for the API provider + - The access token was valid but has now expired + + `400 INVALID_ARGUMENT`: + - The API request is not compliant with this OAS definition + + `400 OUT_OF_RANGE`: + - A parameter value in the API request is outwith the range documented in this OAS definition for that parameter + + `404 IDENTIFIER_NOT_FOUND`: + - The device identified by the `device` object in the request is not managed by the API provider + + `403 PERMISSION_DENIED`: + - The access token does not have the required scope for the endpoint being called + - The end user has not consented to the API consumer getting access to the device identifier information (2-legged access token only) + + `422 SERVICE_NOT_APPLICABLE`: + - The roaming status is not applicable to the identified device. For example, the phone number might identify a landline. + + `422 UNSUPPORTED_IDENTIFIER`: + - A parameter provided in the `device` object is not supported by this implementation (e.g. `networkAccessIdentifier`) + + `422 MISSING_IDENTIFIER`:\ + `422 UNNECESSARY_IDENTIFIER`: + - See the section "Identifying the device from the access token" below + + `429 QUOTA_EXCEEDED`: + - The API consumer has used up the quota of API requests that they were allocated for this API + + `429 TOO_MANY_REQUESTS`: + - The rate at which the API consumer is sending requests has exceeded that allowed by the API provider. Try again later. + + `503 UNAVAILABLE`: + - The API provider is unable to provide the roaming status for the requested device at this time. Try again later. @@ -85,7 +140,7 @@ info: The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. @@ -132,37 +187,21 @@ paths: - openId: - device-roaming-status:read requestBody: + description: Request body definition for the getRoamingStatus operation + required: true content: application/json: schema: $ref: "#/components/schemas/RoamingStatusRequest" examples: - INPUT_PHONE_NUMBER: - summary: Phone number - description: Retrieve roaming status for a device identified by a phone number - value: - device: - phoneNumber: "+123456789" - INPUT_IP_ADDRESS_V4: - summary: IPv4 address - description: Retrieve roaming status for a device identified by an IPv4 address - value: - device: - ipv4Address: - publicAddress: "123.234.1.2" - publicPort: 1234 - INPUT_IP_ADDRESS_V6: - summary: IPv6 address - description: Retrieve roaming status for a device identified by an IPv6 address - value: - device: - ipv6Address: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - INPUT_NO_DEVICE: - summary: Device not provided - description: The device has to be deducted from token - value: - {} - required: true + Identify Device By 3-Legged Access Token: + $ref: '#/components/examples/IdentifyDeviceBy3LeggedToken' + Identify Device By Phone Number: + $ref: '#/components/examples/IdentifyDeviceByPhoneNumber' + Identify Device By IP Address: + $ref: '#/components/examples/IdentifyDeviceByIPAddress' + Identify Device By Multiple Identifiers: + $ref: '#/components/examples/IdentifyDeviceByMultipleIdentifiers' responses: "200": description: Contains information about current roaming status @@ -277,3 +316,33 @@ components: properties: device: $ref: "../common/CAMARA_common.yaml#/components/schemas/Device" + + examples: + IdentifyDeviceBy3LeggedToken: + description: Empty JSON when device is identified by access token + value: + {} + + IdentifyDeviceByPhoneNumber: + description: Identifying device by phone number + value: + device: + phoneNumber: "+123456789" + + IdentifyDeviceByIPAddress: + description: Identifying device by IP address + value: + device: + ipv4Address: + publicAddress: "84.125.93.10" + publicPort: 59765 + + IdentifyDeviceByMultipleIdentifiers: + description: Identifying device by multiple device identifiers + value: + device: + phoneNumber: "+123456789" + ipv4Address: + publicAddress: "84.125.93.10" + publicPort: 59765 + networkAccessIdentifier: "123456789@example.com"