Added clarification of notifications to be sent and added StatusInfo "DELETE_REQUESTED" to addres #241

code/API_definitions/qod-api.yaml

@@ -38,7 +38,7 @@ info:
     Duration (in seconds) for which the QoS session (between application client and application server) should be created. This parameter is optional. When not specified, a default session duration (e.g. 24 hours) is applied. The user may request a termination before its expiration.
 
     * **Notification URL and token**:
-    Developers may provide a callback URL on which notifications (eg. session termination) regarding the session can be received from the service provider. This is an optional parameter.
+    Developers may provide a callback URL on which notifications about all status change events of the session (eg. session termination) can be received from the service provider. This is an optional parameter.
 
     # API functionality
 
@@ -92,7 +92,14 @@ paths:
       tags:
         - QoS Sessions
       summary: Creates a new session
-      description: Create QoS Session to manage latency/throughput priorities
+      description: |
+        Create QoS Session to manage latency/throughput priorities
+
+        If the notification callback is provided the client will receive in addition to the response a `QOS_STATUS_CHANGED` event with either
+        - `qosStatus` as `AVAILABLE` when the session has been provided by the network, or
+        - `qosStatus` as `UNAVAILABLE` if the requested session is currently not available.
+
+        If the `qosStatus` in the API response is `REQUESTED`, the notification will be sent either after the network notifies that it has created the requested session or after the network notifies that it has failed to provide the requested session.
       operationId: createSession
       requestBody:
         description: Parameters to create a new session
@@ -110,7 +117,7 @@ paths:
               summary: "Session notifications callback"
               description: |
                 Important: this endpoint is to be implemented by the API consumer.
-                The QoD server will call this endpoint whenever any network related event occurs.
+                The QoD server will call this endpoint whenever any QoS session change (e.g. network termination) related event occurs.
                 Currently only QOS_STATUS_CHANGED event is defined.
               operationId: postNotification
               requestBody:
@@ -273,7 +280,12 @@ paths:
       tags:
         - QoS Sessions
       summary: Delete a QoS session
-      description: Free resources related to QoS session
+      description: |
+        Free resources related to QoS session
+
+        If the notification callback is provided the client will receive in addition to the response a `QOS_STATUS_CHANGED` event with
+        - `qosStatus` as `UNAVAILABLE` and
+        - `statusInfo` as `USER_DELETED`
       operationId: deleteSession
       parameters:
         - name: sessionId
@@ -887,10 +899,12 @@ components:
         Reason for the new `qosStatus`. Currently `statusInfo` is only applicable when `qosStatus` is 'UNAVAILABLE'.
         * `DURATION_EXPIRED` - Session terminated due to requested duration expired
         * `NETWORK_TERMINATED` - Network terminated the session before the requested duration expired
+        * `DELETE_REQUESTED`- User requested the deletion of the session before the requested duration expired
       type: string
       enum:
         - DURATION_EXPIRED
         - NETWORK_TERMINATED
+        - DELETE_REQUESTED
 
     Device:
       description: |
@@ -1034,8 +1048,8 @@ components:
     EventQosStatus:
       description: |
         The current status of a requested or previously available session. Applicable values in the event are:
-        *  `AVAILABLE` - The requested QoS has been provided by the network
-        *  `UNAVAILABLE` - A requested or previously available QoS session is currently unavailable. `statusInfo` may provide additional information about the reason for the unavailability.
+        *  `AVAILABLE` - The requested QoS has been provided by the network. NOTE: this event will be sent always, also if status within the response to `createSession` is already `AVAILABLE`
+        *  `UNAVAILABLE` - A requested or previously available QoS session is currently unavailable. `statusInfo` may provide additional information about the reason for the unavailability. NOTE: this event will be sent always, also if the user deletes the session explicitly
       type: string
       enum:
         - AVAILABLE