[Changed] Improve documentation and fix typos

code/API_definitions/device-reachability-status-subscriptions.yaml

@@ -2,79 +2,81 @@ 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
 
-    ## 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
 
-    * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication.
+    * **Reachable**:\
+       A device is considered to be reachable if it has mobile data connectivity, or can receive SMS messages.
 
-        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.
+    * **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.
 
-        Note: Network Access Identifier is defined for future use and will not be supported with this version of the API.
+    * **Device**:\
+      A device refers to any physical hardware that can connect to a mobile network and participate in network communication.
 
-    # API Functionality
+      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.
 
-    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 reachability status subscription
+    # API Functionality
 
-    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.
+    The API exposes following capability:
 
-    When subscribing, it is mandatory to provide the event `types` you are subscribing to, as multiple subscription-types are managed by this API.
+    ## Device Reachability Status Subscription
 
-    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.
+    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.
 
-    It is 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 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 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
 
-    **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 initial event is triggered because `initialEvent` set to true, that event will count towards `subscriptionMaxEvents` if that has been specified.
 
-    **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:
 
-    | 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 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            |
+    | 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 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 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`._
 
     <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
 

code/API_definitions/device-reachability-status.yaml

@@ -6,31 +6,84 @@ 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 mobile network via data and/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.
+    * **Reachable**:\
+       A device is considered to be reachable if it has mobile data connectivity, or can receive SMS messages.
 
-        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.
+    * **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.
 
-        Note: Network Access Identifier is defined for future use and will not be supported with this version of the API.
+    * **Device**:\
+      A device refers to any physical entity that can connect to a network and participate in network communication.
 
-    * **Reachable:** Indicates, if the device is reachable from the network or not.
+      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.
 
-    * **Connectivity:** Indicates the connectivity types (DATA, SMS or both) through which the device is reachable from the network.
+      Note: Network Access Identifier is defined for future use and will not be supported with this version of 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 device reachability status was last confirmed to be correct. An older status is more likely to now be incorrect.
 
     # API Functionality
 
     The API exposes following capabilities:
 
-    ### Device Reachability situation
+    ## 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`:
+    - 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`)
+
+    `422 MISSING_IDENTIFIER`:\
+    `422 UNNECESSARY_IDENTIFIER`:
+    - See the section "Identifying the device from the access token" below
 
-    The endpoint `POST /retrieve` allows to get current connectivity status information synchronously.
+    `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.
 
     <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
 
@@ -124,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
@@ -230,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"