From 0996d1b4c3ceb46f0bfdc9b2debc023935a676ae Mon Sep 17 00:00:00 2001
From: Herbert Damker <52109189+hdamker@users.noreply.github.com>
Date: Tue, 23 Jan 2024 13:44:37 +0100
Subject: [PATCH] Clarified notifications and added StatusInfo "USER_DELETED"
 (#7)

---
 code/API_definitions/qod-api.yaml | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml
index 9038269ca5..9242dbbf0a 100644
--- 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