From 78aea27388c3eb920f6e4ac8153009ca8347c1d2 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 09:32:37 +0100 Subject: [PATCH 01/21] Update reachability status subscription table --- ...ice-reachability-status-subscriptions.yaml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index cd90c59..9a66b62 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -57,15 +57,16 @@ info: Following table illustrate behaviour regarding event triggering depending on **initial** reachability state of the device: - | subscribed event-type | device reachability status at subscription time | event sent if ``initialEvent`` set to true | Explanation | - | ----------------------| ------------- | --------------- | ---------------| - | reachability-data | Device can use data | Yes | The device is reachable for data, so the event is triggered. | - | reachability-data | Device is disconnected or SMS-only | No | The device cannot use data, so no event is sent. | - | reachability-sms | Device can use data | No | The device can use data, but for thids event is only for SMS. | - | reachability-sms | Device is SMS-only | Yes | The device supports SMS, so the event is triggered. | - | reachability-sms | Device is disconnected | No | The device cannot send SMS, so no event is send. | - | reachability-disconnected | Device can use data or SMS usage | No | The device is reachable, so no "disconnected" event is sent. | - | reachability-disconnected | Device is disconnected | Yes | The device is disconnected, so the event is triggered. | + | subscribed event-type | device reachability status at subscription time | event sent if ``initialEvent`` is true | Explanation | + | -------------------------- | ------------------------------------------------ | -------------------------------------- | --------------------------------------------- | + | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | + | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | + | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | + | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | + | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | + | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | + | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | + | reachability-disconnected | Device is connected for data and/or SMS | No | The device is reachable using data and/or SMS | ### Notifications callback From 80440cef955b7277edd20e5944e47cbbfa6fd58c Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 09:36:23 +0100 Subject: [PATCH 02/21] Refactor reachability status event table formatting Updated the table formatting for clarity on event triggering based on device reachability status. --- ...ice-reachability-status-subscriptions.yaml | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 9a66b62..b7b7892 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -57,16 +57,16 @@ info: Following table illustrate behaviour regarding event triggering depending on **initial** reachability state of the device: - | subscribed event-type | device reachability status at subscription time | event sent if ``initialEvent`` is true | Explanation | - | -------------------------- | ------------------------------------------------ | -------------------------------------- | --------------------------------------------- | - | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | - | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | - | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | - | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | - | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | - | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | - | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | - | reachability-disconnected | Device is connected for data and/or SMS | No | The device is reachable using data and/or SMS | + | subscribed event-type | device reachability status at subscription time | event sent if `initialEvent` is true | Explanation | + | -------------------------- | ------------------------------------------------ | ------------------------------------ | --------------------------------------------- | + | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | + | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | + | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | + | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | + | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | + | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | + | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | + | reachability-disconnected | Device is connected for data and/or SMS | No | The device is reachable using data and/or SMS | ### Notifications callback From ef18d9fe80b2caa7e7e6a1c825b16ae3c0eb6397 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 09:44:41 +0100 Subject: [PATCH 03/21] Refine event notification and callback endpoint details Updated the description of the event notification format and the callback endpoint requirements for API consumers. --- .../device-reachability-status-subscriptions.yaml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index b7b7892..4e4a25f 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -70,12 +70,13 @@ info: ### 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`._ From f2dbaea080455d102234b780ad29dc20ec5eb884 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 09:55:46 +0100 Subject: [PATCH 04/21] Fix formatting issues in YAML documentation --- ...ice-reachability-status-subscriptions.yaml | 34 +++++++++---------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 4e4a25f..e6b55db 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -48,35 +48,33 @@ info: - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached - the API server 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 following ``initialEvent`` set to true, - this event will be counted towards ``subscriptionMaxEvents`` (if provided). + 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:** + **Clarification on `initialEvent` & `event-type` behaviour:** Following table illustrate behaviour regarding event triggering depending on **initial** reachability state of the device: - | subscribed event-type | device reachability status at subscription time | event sent if `initialEvent` is true | Explanation | - | -------------------------- | ------------------------------------------------ | ------------------------------------ | --------------------------------------------- | - | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | - | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | - | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | - | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | - | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | - | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | - | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | - | reachability-disconnected | Device is connected for data and/or SMS | No | The device is reachable using data and/or SMS | + | subscribed event-type | device reachability status at subscription time | event sent if `initialEvent` is `true` | Explanation | + | -------------------------- | ------------------------------------------------ | -------------------------------------- | --------------------------------------------- | + | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | + | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | + | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | + | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | + | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | + | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | + | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | + | reachability-disconnected | Device is connected for data and/or SMS | No | The device is reachable using data and/or SMS | ### Notifications callback 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**: - 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`._ + _**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`._ From 99e3ab11526d1cf40337cc9d8d4bb2abc052054e Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 10:35:38 +0100 Subject: [PATCH 05/21] Fix formatting of event type descriptions in YAML --- .../device-reachability-status-subscriptions.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index e6b55db..a98f5e6 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -30,11 +30,11 @@ info: 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 ``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 (regardless of the SMS reachability). + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data`: Event triggered when the device is connected to the network for Data usage (regardless of the SMS reachability). - - ``org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms``: Event triggered when the device is connected to the network only for SMS usage + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms`: Event triggered when the device is connected to the network only for SMS usage - - ``org.camaraproject.device-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, the following events could be sent, which do not require a dedicated subscription: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-started` is sent when the subscription starts. @@ -62,7 +62,7 @@ info: | reachability-data | Device is connected for data and possibly SMS | Yes | The device is reachable using data | | reachability-data | Device is connected for SMS only | No | The device is not reachable using data | | reachability-data | Device is disconnected from the network | No | The device is not reachable using data | - | reachability-sms | Device is connected for SMS and possibly data | Yes | The device is reachable using SMS | + | reachability-sms | Device is connected for SMS but not data | Yes | The device is reachable only using SMS | | reachability-sms | Device is connected for data only | No | The device is not reachable using SMS | | reachability-sms | Device is disconnected from the network | No | The device is not reachable using SMS | | reachability-disconnected | Device is disconnected from the network | Yes | The device is not reachable at all | @@ -71,7 +71,7 @@ info: ### Notifications callback 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. + A detailed description of the event subscription and notification mechanism is provided in the `CAMARA API Event Subscription and Notification Guide`. _**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`._ From 9cd673de122c140a6e49372129125446108a0f04 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:34:29 +0100 Subject: [PATCH 06/21] Update device reachability status API documentation Revised the description of reachability status notifications and clarified subscription management for device reachability events. --- ...ice-reachability-status-subscriptions.yaml | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index a98f5e6..9e3adea 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -6,12 +6,12 @@ info: # Introduction - ## Reachability Status - API consumer is able to be notified whether the reachability status of a certain user device has changed to either data- or sms-usage. - This capability is provided via a subscription request - in this case the reachability situation is part of the event notification, which is sent back to the event subscriber when reachability situation has changed. + The API consumer is able to be notified whenever the reachability status of a certain user device has changed for either data or SMS connectivity. This capability is requested via a subscription request - in this case the reachability status is not contained in the API response, but instead an event notification is sent back to the event subscriber whenever the reachability situation changes. # Relevant terms and definitions + * **Reachable**: A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + * **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 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. @@ -24,17 +24,15 @@ info: ## Device reachability status subscription - 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 `types` you are subscribing to, as multiple subscription-types are managed by this API. - - 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 (regardless of the SMS reachability). + These endpoints allow the API consumer to manage event subscriptions for device reachability status events. + The CAMARA subscription model is described in the `CAMARA API Event Subscription and Notification Guide` and uses notifications that follow the CloudEvents specification. - - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms`: Event triggered when the device is connected to the network only for SMS usage + When creating a subscription, it is mandatory to provide the event types you are subscribing to, as multiple subscription-types are managed by this API. - - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected`: Event triggered when the device is not connected. + 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 (regardless of the SMS reachability) + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms` : Event triggered when the device is connected to the network only for SMS usage + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected` : Event triggered when the device is not connected Note: Additionally, the following events could be sent, which do not require a dedicated subscription: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-started` is sent when the subscription starts. From 624e1372787221eb925b3a58394e90580596eb75 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:46:43 +0100 Subject: [PATCH 07/21] Format YAML definitions for readability --- .../device-reachability-status-subscriptions.yaml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 9e3adea..6764434 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -10,13 +10,15 @@ info: # Relevant terms and definitions - * **Reachable**: A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + * **Reachable**:\ + A device is considered to be reachable if it has data connectivity, or can receive SMS messages. - * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + * **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 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. + 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 session creation response. - Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. + Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. # API Functionality @@ -51,7 +53,7 @@ info: 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:** + **Clarification on `initialEvent` setting and event type behaviour:** Following table illustrate behaviour regarding event triggering depending on **initial** reachability state of the device: From d691171b7c4c50a648d55e1fc8387aa8661bf836 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:51:50 +0100 Subject: [PATCH 08/21] Update device reachability status documentation --- .../device-reachability-status.yaml | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 9b2d9b9..ee048ad 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -6,23 +6,25 @@ info: # Introduction - ## Reachability Status - - API consumer is able to verify whether a certain user device is reachable from the network via data- or sms-usage. + The API consumer is able to verify whether a certain user device is reachable from the network via data or SMS connectivity. ## Relevant terms and definitions - * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + * **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 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. + 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. - Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. + Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. - * **Reachable:** Indicates, if the device is reachable from the network or not. + * **Reachable:**\ + Indicates, if the device is reachable from the network or not. - * **Connectivity:** Indicates the connectivity types (DATA, SMS or both) through which the device is reachable from the network. + * **Connectivity:**\ + Indicates the connectivity types (DATA, SMS or both) through which the device is reachable from the network. - * **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 device reachability status was last confirmed to be correct. An older status is more likely to now be incorrect. # API Functionality From 660d4c451fdd6e70b574759ad2bdbe55048358d7 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:54:11 +0100 Subject: [PATCH 09/21] Refine definitions in device reachability status YAML Removed redundant definitions for 'Reachable' and 'Connectivity' to streamline the document. --- code/API_definitions/device-reachability-status.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index ee048ad..523c786 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -10,6 +10,12 @@ info: ## Relevant terms and definitions + * **Reachable**:\ + A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + + * **Connectivity:**\ + Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. + * **Device**:\ A device refers to any physical entity that can connect to a network and participate in network communication. @@ -17,12 +23,6 @@ info: Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. - * **Reachable:**\ - Indicates, if the device is reachable from the network or not. - - * **Connectivity:**\ - Indicates the connectivity types (DATA, SMS or both) through which the device is reachable from the network. - * **Last Status Time**:\ The time when the device reachability status was last confirmed to be correct. An older status is more likely to now be incorrect. From 3b0a5db8050bdcf0cb8550fc6381f6e491678e4a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:55:35 +0100 Subject: [PATCH 10/21] Clarify device reachability status in API documentation Updated the API documentation to clarify the reachability status. --- code/API_definitions/device-reachability-status.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 523c786..5a1a7eb 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -30,9 +30,9 @@ info: The API exposes following capabilities: - ### Device Reachability situation + ### Device Reachability Status - The endpoint `POST /retrieve` allows to get current connectivity status information synchronously. + The endpoint `POST /retrieve` allows to get current reachability status information synchronously for a specific device From ac79ca6f33a9fac76c94dedf6b6e431234efb3eb Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:57:37 +0100 Subject: [PATCH 11/21] Update device-reachability-status.yaml --- code/API_definitions/device-reachability-status.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 5a1a7eb..102a21c 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -14,7 +14,7 @@ info: A device is considered to be reachable if it has data connectivity, or can receive SMS messages. * **Connectivity:**\ - Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. + Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. A device is considered to be disconnected if it cannot be reached using either data or SMS connectivity. * **Device**:\ A device refers to any physical entity that can connect to a network and participate in network communication. From c7888507b2fe588bf089619c576d4e7a29914043 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 16:57:55 +0100 Subject: [PATCH 12/21] Add 'Connectivity' definition to reachability status Added definition for 'Connectivity' in device reachability status. --- .../device-reachability-status-subscriptions.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 6764434..4e95ade 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -13,6 +13,9 @@ info: * **Reachable**:\ A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + * **Connectivity:**\ + Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. A device is considered to be disconnected if it cannot be reached using either data or SMS connectivity. + * **Device**:\ A device refers to any physical entity that can connect to a network and participate in network communication. From 84c315488207708d51991d8409ba86a56b38f275 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 12 Aug 2026 17:09:06 +0100 Subject: [PATCH 13/21] Refine descriptions for device reachability events Updated event type descriptions for clarity and consistency. --- .../device-reachability-status-subscriptions.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 4e95ade..07546ad 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -27,7 +27,7 @@ info: The API exposes following capability: - ## Device reachability status subscription + ## Device Reachability Status Subscription These endpoints allow the API consumer to manage event subscriptions for device reachability status events. The CAMARA subscription model is described in the `CAMARA API Event Subscription and Notification Guide` and uses notifications that follow the CloudEvents specification. @@ -35,9 +35,9 @@ info: When creating a subscription, it is mandatory to provide the event types you are subscribing to, as multiple subscription-types are managed by this API. 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 (regardless of the SMS reachability) - - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms` : Event triggered when the device is connected to the network only for SMS usage - - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected` : Event triggered when the device is not connected + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data` is sent when the device becomes connected to the network for data usage (regardless of the SMS reachability status) + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms` is sent when the device becomes connected to the network for SMS usage (regardless of the data reachability status) + - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected` is sent when the device becomes disconnected from the network Note: Additionally, the following events could be sent, which do not require a dedicated subscription: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-started` is sent when the subscription starts. From 308c2b777c0429bb9f439f7a381d4beaef3e5c48 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 2 Oct 2026 16:34:08 +0100 Subject: [PATCH 14/21] Clarify device reachability and API documentation Updated terminology to specify 'mobile network' and clarified device reachability definitions. Enhanced API documentation for better understanding of connectivity and error handling. --- .../device-reachability-status.yaml | 101 +++++++++++++++++- 1 file changed, 96 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 349575f..0150f27 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -6,15 +6,15 @@ info: # Introduction - The API consumer is able to verify whether a certain user device is reachable from the network via data or SMS connectivity. + The API consumer is able to verify whether a certain user device is reachable from the mobile network via data and/or SMS connectivity. ## Relevant terms and definitions * **Reachable**:\ - A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + A device is considered to be reachable if it has mobile data connectivity, or can receive SMS messages. * **Connectivity:**\ - Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. A device is considered to be disconnected if it cannot be reached using either data or SMS connectivity. + Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the mobile network. A device is considered to be not reachable if it cannot be reached using either data or SMS connectivity. * **Device**:\ A device refers to any physical entity that can connect to a network and participate in network communication. @@ -30,10 +30,61 @@ info: The API exposes following capabilities: - ### Device Reachability Status + ## Device Reachability Status The endpoint `POST /retrieve` allows to get current reachability status information synchronously for a specific device + An example of a JSON response object is as follows: + ``` + { + "lastStatusTime": "2024-02-20T10:41:38.657Z", + "reachable": true, + "connectivity": [ + "DATA", + "SMS" + ] + } + ``` + + ## 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`: + - A device identifier cannot be provided for 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 reachability status for the requested device at this time. Try again later. + # Authorization and authentication @@ -126,11 +177,21 @@ paths: - openId: - device-reachability-status:read requestBody: + description: Request body definition for the getReachabilityStatus operation + required: true content: application/json: schema: $ref: "#/components/schemas/RequestReachabilityStatus" - required: true + examples: + 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 reachability status @@ -232,3 +293,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" From 9294b925b88ba922df9f335dd9d296deb5e228d3 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 2 Oct 2026 16:36:52 +0100 Subject: [PATCH 15/21] Update error message for reachability status --- code/API_definitions/device-reachability-status.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 0150f27..a7d93e6 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -67,7 +67,7 @@ info: - 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`: - - A device identifier cannot be provided for the identified device. For example, the phone number might identify a landline. + - The reachability 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`) From 4189aa6f72da4368c255283fbaec412485655da2 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 6 Oct 2026 12:45:12 +0100 Subject: [PATCH 16/21] Refine language in device reachability API documentation Updated terminology for clarity and consistency in the API documentation. --- ...ice-reachability-status-subscriptions.yaml | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 05da909..320a236 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Device Reachability Status Subscriptions description: | - This API provides the API consumer with the ability to subscribe to Reachability status events. + This API provides the API consumer with the ability to subscribe to reachability status events. # Introduction @@ -11,13 +11,13 @@ info: # Relevant terms and definitions * **Reachable**:\ - A device is considered to be reachable if it has data connectivity, or can receive SMS messages. + A device is considered to be reachable if it has mobile data connectivity, or can receive SMS messages. * **Connectivity:**\ - Indicates the connectivity types (data, SMS, or both) by which the device is reachable from the network. A device is considered to be disconnected if it cannot be reached using either data or SMS connectivity. + Indicates the connectivity types (mobile data, SMS, or both) by which the device is reachable from the network. A device is considered to be disconnected if it cannot be reached using either mobile data or SMS connectivity. * **Device**:\ - A device refers to any physical entity that can connect to a network and participate in network communication. + A device refers to any physical hardware that can connect to a mobile network and participate in network communication. 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 session creation response. @@ -34,12 +34,12 @@ info: When creating a subscription, it is mandatory to provide the event types you are subscribing to, as multiple subscription-types are managed by this API. - Following event types are managed for this API: + The following event types may be requested for this API: - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-data` is sent when the device becomes connected to the network for data usage (regardless of the SMS reachability status) - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-sms` is sent when the device becomes connected to the network for SMS usage (regardless of the data reachability status) - `org.camaraproject.device-reachability-status-subscriptions.v0.reachability-disconnected` is sent when the device becomes disconnected from the network - Note: Additionally, the following events could be sent, which do not require a dedicated subscription: + Note: Additionally, the following events may be sent, which do not require a dedicated subscription: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-started` is sent when the subscription starts. - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-updated` is sent when the subscription is updated. - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ended` is sent when the subscription ends. @@ -48,13 +48,12 @@ info: - 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 expiry time for the access token `sinkCredential` (optionally set by the API consumer) time has been reached + - the API provider has to stop sending notifications early **Note on combined usage of `initialEvent` and `subscriptionMaxEvents`**: - If an event is triggered following `initialEvent` set to true, - this event will be counted towards `subscriptionMaxEvents` (if provided). + If an initial event is triggered because `initialEvent` set to true, that event will count towards `subscriptionMaxEvents` if that has been specified. **Clarification on `initialEvent` setting and event type behaviour:** @@ -77,7 +76,7 @@ info: A detailed description of the event subscription and notification mechanism is provided in the `CAMARA API Event Subscription and Notification Guide`. _**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`._ + API consumers must 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 URL specified by `sink`._ From 27693f02ffe7988919903eab6c1810b99d7fa532 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 6 Oct 2026 12:48:10 +0100 Subject: [PATCH 17/21] Update subscription-ended event usage description Clarified the usage of the `subscription-ended` event and updated the wording for consistency. --- .../device-reachability-status-subscriptions.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 320a236..6d2cf31 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -44,10 +44,10 @@ info: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-updated` is sent when the subscription is updated. - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ended` is sent when the subscription ends. - It is used in following cases: + The `subscription-ended` event may 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 subscription was deleted by the API consumer - the expiry time for the access token `sinkCredential` (optionally set by the API consumer) time has been reached - the API provider has to stop sending notifications early From 49874afa7980dfebad7c90bd5337be01b9c7d0d3 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 6 Oct 2026 13:06:25 +0100 Subject: [PATCH 18/21] Clarify device identifier selection in API definition Updated the response description for device identifier selection. --- code/API_definitions/device-reachability-status.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index a7d93e6..30f9405 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -19,7 +19,7 @@ info: * **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 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. + 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 reachability status. Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. From 78665e01be1882bf670ae67b8b81f6bd6b7896ae Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 6 Oct 2026 13:12:26 +0100 Subject: [PATCH 19/21] Fix formatting for 422 MISSING_IDENTIFIER error documentation --- code/API_definitions/device-reachability-status.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index 30f9405..fc57ca6 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -72,7 +72,7 @@ info: `422 UNSUPPORTED_IDENTIFIER`: - A parameter provided in the `device` object is not supported by this implementation (e.g. `networkAccessIdentifier`) - `422 MISSING_IDENTIFIER`: + `422 MISSING_IDENTIFIER`:\ `422 UNNECESSARY_IDENTIFIER`: - See the section "Identifying the device from the access token" below From 9b9b332a90156729329c310c3e5e3c4a2381335a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 9 Oct 2026 13:56:57 +0100 Subject: [PATCH 20/21] Fix capitalization in device reachability status YAML Corrected capitalization of 'Phone' and 'Network Access Identifier' for consistency. --- code/API_definitions/device-reachability-status.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/device-reachability-status.yaml b/code/API_definitions/device-reachability-status.yaml index fc57ca6..0d275f2 100644 --- a/code/API_definitions/device-reachability-status.yaml +++ b/code/API_definitions/device-reachability-status.yaml @@ -19,7 +19,7 @@ info: * **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 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 reachability status. + 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 reachability status. Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. From bf270872e360d5cf8879c39c1799bd45ce6b2cd5 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 9 Oct 2026 13:57:48 +0100 Subject: [PATCH 21/21] Fix grammar and capitalization in YAML documentation --- .../device-reachability-status-subscriptions.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/device-reachability-status-subscriptions.yaml b/code/API_definitions/device-reachability-status-subscriptions.yaml index 6d2cf31..5f9e28e 100644 --- a/code/API_definitions/device-reachability-status-subscriptions.yaml +++ b/code/API_definitions/device-reachability-status-subscriptions.yaml @@ -19,7 +19,7 @@ info: * **Device**:\ A device refers to any physical hardware that can connect to a mobile network and participate in network communication. - 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 session creation response. + 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 session creation response. Note: Network Access Identifier is defined for future use and will not be supported with this version of the API. @@ -44,7 +44,7 @@ info: - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-updated` is sent when the subscription is updated. - `org.camaraproject.device-reachability-status-subscriptions.v0.subscription-ended` is sent when the subscription ends. - The `subscription-ended` event may used in following cases: + The `subscription-ended` event may be 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 API consumer