QoS B: Update documentation

code/API_definitions/qos-booking.yaml

@@ -6,14 +6,16 @@
 
     The API enables API consumers to book the assignment of a predefined QoS profile to a specific device, with some conditions such as the start time, duration and location.
 
+    The lifecycle of a booking is expressed by the `BookingStatus` value and typically follows this pattern: a booking is accepted as `REQUESTED`, then it may become `SCHEDULED` for a future start, then `ACTIVATED` once the start time comes, and it eventually becomes `TERMINATED` when the booking expires, is cancelled or is rejected.
+
 
     # Relevant terms and definitions
 
     * **QoS profiles**:
     Latency, throughput or priority requirements of the application mapped to relevant QoS profile values. The set of QoS Profiles that a network operator is offering may be retrieved via the `qos-profiles` API (cf. https://github.com/camaraproject/QualityOnDemand/) or will be agreed during the onboarding with the API service provider.
 
     * **Identifier for the device**:
-    At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the network operator for the device, at the request time. After the booking request is accepted, the device may get different IP addresses, but the booking will still apply to the device that was identified during the request process. Note: Network Access Identifier is defined for future use and will not be supported with v0.1 of the API.
+    At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the network operator for the device, at the request time. After the booking request is accepted, the device may get different IP addresses, but the booking will still apply to the device that was identified during the request process. Note: Network Access Identifier is defined for future use and is not supported in this version of the API.
 
     * **Notification URL and token**:
     API consumers may provide a callback URL (`sink`) on which notifications about all status change events (e.g. duration expiration) can be received from the API provider. This is an optional parameter. The notification will be sent as a CloudEvent compliant message. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` property to protect the notification endpoint. In the current version,`sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided.
@@ -27,6 +29,7 @@
     - An operation to terminate a QoS Booking, identified by its `BookingId`.
 
     <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
+
     # Authorization and authentication
 
     The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
@@ -37,6 +40,7 @@
     <!-- CAMARA:MANDATORY:authorization-and-authentication:END -->
 
     <!-- CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN -->
+
     # Identifying the device from the access token
 
     This API requires the API consumer to identify a device as the subject of the API as follows:
@@ -55,6 +59,7 @@
     - If the requested `qosProfile` exists but is currently not available for creating a booking, then the server will return an error with the `422 QOS_BOOKING.QOS_PROFILE_NOT_APPLICABLE` error code.
 
     <!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->
+
     # Additional CAMARA error responses
 
     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`.
@@ -65,6 +70,7 @@
     <!-- CAMARA:MANDATORY:additional-error-responses:END -->
 
     <!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->
+
     # Request body strictness
 
     This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
@@ -682,7 +688,7 @@
           required:
             - areaName
           properties:
             areaName:
               type: string
               maxLength: 256
 
@@ -692,10 +698,10 @@
     Point:
       $ref: '../common/CAMARA_common.yaml#/components/schemas/Point'
 
     Latitude:
       $ref: '../common/CAMARA_common.yaml#/components/schemas/Latitude'
 
     Longitude:
       $ref: '../common/CAMARA_common.yaml#/components/schemas/Longitude'
 
     Device:
@@ -717,7 +723,7 @@
           $ref: "#/components/schemas/ApplicationServerIpv6Address"
       minProperties: 1
 
     ApplicationServerIpv4Address:
       type: string
       maxLength: 15
       example: "198.51.100.0/24"
@@ -727,7 +733,7 @@
           - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
             In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.
 
     ApplicationServerIpv6Address:
       type: string
       maxLength: 45
       example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"