Clarified notifications and added StatusInfo "USER_DELETED" (#7)

camaraproject · Jan 23, 2024 · 0996d1b · 0996d1b
1 parent 466b0c7
commit 0996d1b
Showing 1 changed file with 20 additions and 6 deletions.
diff --git a/code/API_definitions/qod-api.yaml b/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.
+
+        In case that the  `qosStatus` in the response is `REQUESTED` the notification will be send after the session has been provided by the network or couldn't be provided
       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
+        * `USER_DELETED`- User deleted the session before the requested duration expired
       type: string
       enum:
         - DURATION_EXPIRED
         - NETWORK_TERMINATED
+        - USER_DELETED
 
     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 send 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 send always, also if the user deletes the session explicitly
       type: string
       enum:
         - AVAILABLE