From 8f537ebc17ce59be83e07a9b9bad8952660280f7 Mon Sep 17 00:00:00 2001
From: Jose Luis Urien <joseluis.urienpinedo@telefonica.com>
Date: Wed, 29 May 2024 17:27:04 +0200
Subject: [PATCH 1/4] Consolidation of changes related to session duration

- For creation, duration is made required. Maximum and default are deprecated, relying on the QoS Profile API for any limit. Implementations can grant the requested duration or set a different value in the response.
- maxDuration in QoS Profiles is assumed to be the absolute maximum duration including any extensions. That is, extensions can extend the current session duration to the maximumDuration but no longer.

Session info changes:

- dates are formatted as string, date-format.
- startedAt and expiredAt are both optional and not expected to be returned when qosStatus is "REQUESTED".
- duration is the overall session duration, including any extension. It should be the interval between startedAt and expiresAt, so it is redundant, unless the qosStatus is "REQUESTED". In this case it would reflect the requested or granted duration. For sessions with qosStatus = "UNAVAILABLE", it must be adjusted to the effective duration.
---
 code/API_definitions/qos-profiles.yaml      |  3 +-
 code/API_definitions/quality-on-demand.yaml | 88 +++++++++++----------
 2 files changed, 46 insertions(+), 45 deletions(-)

diff --git a/code/API_definitions/qos-profiles.yaml b/code/API_definitions/qos-profiles.yaml
index 091b9d3b73..7b28940b57 100644
--- a/code/API_definitions/qos-profiles.yaml
+++ b/code/API_definitions/qos-profiles.yaml
@@ -231,8 +231,7 @@ components:
         maxDuration:
           description: |
             The maximum time period that this profile can be deployed.
-            NOTE: currently the duration within `sessionInfo` is limited to 86400 seconds (1 day).
-            The value of `maxDuration` shouldn't therefore exceed this time period. The limitation might be removed in later versions.
+            Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions.
           allOf:
             - $ref: "#/components/schemas/Duration"
         priority:
diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml
index 5363730a65..76ba138ee1 100644
--- a/code/API_definitions/quality-on-demand.yaml
+++ b/code/API_definitions/quality-on-demand.yaml
@@ -12,7 +12,7 @@ info:
 
     ![QoD API Overview](https://raw.githubusercontent.com/camaraproject/QualityOnDemand/main/documentation/API_documentation/resources/QoD_latency_overview.PNG)
 
-    The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically. The automatic process is triggered either when the requested specified duration of a QoS session has reached its limit or the default session expiration time has been reached (within an example provider implementation it is set to 24hrs).
+    The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically once the QoS session has reached its limit.
 
     # Relevant terms and definitions
 
@@ -35,7 +35,7 @@ info:
     The precise application data flow the developer wants to prioritize and have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the device and the application server. And it can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features.
 
     * **Duration**:
-    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.
+    Duration (in seconds) for which the QoS session (between application client and application server) should be created. Limits for session duration can be set by the implementation for the QoS profile. The user may request a termination before its expiration.
 
     * **Notification URL and token**:
     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.
@@ -97,8 +97,7 @@ paths:
 
         A `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` will also be send if the network terminates the session before the requested duration expired
 
-        NOTE: in case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session
-        are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
+        NOTE: in case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
         This behavior allows clients which are not receiving notification events but are polling to get the session information with
         the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session
         for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
@@ -359,14 +358,12 @@ paths:
         - QoS Sessions
       summary: "Extend the duration of an active session"
       description: |
-        Extend the overall duration of an active QoS session. If this operation is executed successfully, the new duration of the target session will be the original duration plus the additionally requested duration.
-        The new remaining duration of the QoS session shall not exceed the maximum remaining duration limit (currently fixed at 86,400 seconds) where the remaining duration is calculated as the difference between the `expiresAt` and current time when the request to extend the session duration is received. If this maximum limit would be exceeded, the overall duration shall be set such that the remaining duration is equal to this limit.
-        An example: A QoD session was originally created with duration 80,000 seconds. 10,000 seconds later, the developer requested to extend the session by 20,000 seconds.
-        - Original duration: 80,000 seconds
-        - Elapsed time: 10,000 seconds
-        - Remaining duration: 70,000 seconds
-        - New remaining duration: 86,400 seconds (the maximum allowed)
-        - New overall session duration: 96,400 seconds
+        Extend the overall session duration of an active QoS session.
+        The overall duration of the QoS session, including the additional extended duration, shall not exceed the maximum duration limit fixed for the QoS Profile. If the current duration plus the value of `requestedAdditionalDuration` exceeds the maximum limit, the new overall duration shall be capped to the maximum value allowed.
+        An example: For a QoS profile limited to a `maxDuration` of 50,000 seconds, a QoD session was originally created with duration 30,000 seconds. Before the session expires, the developer requests to extend the session by another 30,000 seconds:
+        - Previous duration: 30,000 seconds
+        - Requested additional duration: 30,000 seconds 
+        - New overall session duration: 50,000 seconds (the maximum allowed)
       operationId: extendQosSessionDuration
       parameters:
         - name: sessionId
@@ -527,20 +524,30 @@ components:
             sessionId:
               $ref: "#/components/schemas/SessionId"
             duration:
+              description: |
+                Session duration in seconds. Implementations can grant the requested session duration or set a different duration, based on network policies or conditions. 
+                - When `qosStatus` is "REQUESTED", the value is the duration to be scheduled, granted by the implementation.
+                - When `qosStatus` is AVAILABLE", the value is the overall duration since `startedAt. When the session is extended, the value is the new overall duration of the session. 
+                - When `qosStatus` is "UNAVAILABLE", the value is the overall effective duration since `startedAt` until the session was terminated.
               type: integer
               format: int32
               minimum: 1
-              example: 86400
+              example: 3600
             startedAt:
-              type: integer
-              example: 1639479600
-              description: Timestamp of session start in seconds since Unix epoch
-              format: int64
+              description: Date and time when the QoS status became "AVAILABLE". Not to be returned when `qosStatus` is "REQUESTED". Format must follow RFC 3339 and must indicate time zone (UTC or local).
+              type: string
+              format: date-time
+              example: "2024-06-01T12:00:00Z"
             expiresAt:
-              type: integer
-              example: 1639566000
-              description: Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch
-              format: int64
+              description: |
+                Date and time of the QoS session expiration. Format must follow RFC 3339 and must indicate time zone (UTC or local).
+                - When `qosStatus` is "AVAILABLE", it is the limit time when the session is scheduled to finnish, if not terminated by other means.
+                - When `qosStatus` is "UNAVAILABLE", it is the time when the session was terminated.
+                - Not to be returned when `qosStatus` is "REQUESTED".
+                When the session is extended, the value is the new expiration time of the session.
+              type: string
+              format: date-time
+              example: "2024-06-01T13:00:00Z"
             qosStatus:
               $ref: "#/components/schemas/QosStatus"
             statusInfo:
@@ -552,8 +559,6 @@ components:
           required:
             - sessionId
             - duration
-            - startedAt
-            - expiresAt
             - qosStatus
 
     CreateSession:
@@ -564,17 +569,13 @@ components:
           properties:
             duration:
               description: |
-                Session duration in seconds. Maximal value of 24 hours is used if not set.
-                After session is expired the, client will receive a `QOS_STATUS_CHANGED` event with
-                - `qosStatus` as `UNAVAILABLE`, and,
-                - `statusInfo` as `DURATION_EXPIRED`.
-                See notification callback.
+                Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the [Qos Profile API](TBC). Implementations can grant the requested session duration or set a different duration, based on network policies or conditions. 
               type: integer
               format: int32
               minimum: 1
-              maximum: 86400
-              default: 86400
-              example: 86400
+              example: 3600
+          required:
+            - duration
 
     Port:
       description: TCP or UDP port number
@@ -621,12 +622,11 @@ components:
       properties:
         requestedAdditionalDuration:
           description: |
-            Additional duration in seconds to be extended.
+            Additional duration in seconds to be added to the current session duration. The overall session duration, including extensions, shall not exceed the maximum duration limit for the QoS Profile.
           type: integer
           format: int32
           minimum: 1
-          maximum: 86399
-          example: 60
+          example: 1800
       required:
         - requestedAdditionalDuration
 
@@ -995,8 +995,9 @@ components:
   examples:
     SESSION_AVAILABLE_EXAMPLE:
       summary: QoS session status is available
+      description: QoS session info when status is available
       value:
-        duration: 86400
+        duration: 3600
         device:
           ipv4Address:
             publicAddress: 203.0.113.0
@@ -1007,14 +1008,15 @@ components:
         webhook:
           notificationUrl: https://application-server.com
         sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
-        startedAt: 1639479600
-        expiresAt: 1639566000
+        startedAt: "2024-06-01T12:00:00Z"
+        expiresAt: "2024-06-01T13:00:00Z"
         qosStatus: AVAILABLE
 
     SESSION_UNAVAILABLE_EXAMPLE:
       summary: QoS session is unavailable
+      description: QoS session info when status is unavailable due to network termination
       value:
-        duration: 86400
+        duration: 2428
         device:
           ipv4Address:
             publicAddress: 203.0.113.0
@@ -1025,20 +1027,20 @@ components:
         webhook:
           notificationUrl: https://application-server.com
         sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
-        startedAt: 1639479600
-        expiresAt: 1639566000
+        startedAt: "2024-06-01T12:00:00Z"
+        expiresAt: "2024-06-01T12:40:28Z"
         qosStatus: UNAVAILABLE
         statusInfo: NETWORK_TERMINATED
 
     QOS_STATUS_CHANGED_EXAMPLE:
-      description: QoS status changed
-      summary: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
+      summary: QoS status changed
+      description: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
       value:
         id: 83a0d986-0866-4f38-b8c0-fc65bfcda452
         source: 'https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000'
         specversion: '1.0'
         type: 'org.camaraproject.qod.v0.qos-status-changed'
-        time: '2021-12-12T00:00:00Z'
+        time: '2024-06-01T13:00:00Z'
         data:
           sessionId: '123e4567-e89b-12d3-a456-426614174000'
           qosStatus: 'UNAVAILABLE'

From 068b65158cd2fa1e6303e19c829244039d3aad5f Mon Sep 17 00:00:00 2001
From: Jose Luis Urien <joseluis.urienpinedo@telefonica.com>
Date: Fri, 31 May 2024 12:57:09 +0200
Subject: [PATCH 2/4] Update quality-on-demand.yaml

Fixing linting complaints about trailing spaces
---
 code/API_definitions/quality-on-demand.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml
index 76ba138ee1..b4c4f16a14 100644
--- a/code/API_definitions/quality-on-demand.yaml
+++ b/code/API_definitions/quality-on-demand.yaml
@@ -362,7 +362,7 @@ paths:
         The overall duration of the QoS session, including the additional extended duration, shall not exceed the maximum duration limit fixed for the QoS Profile. If the current duration plus the value of `requestedAdditionalDuration` exceeds the maximum limit, the new overall duration shall be capped to the maximum value allowed.
         An example: For a QoS profile limited to a `maxDuration` of 50,000 seconds, a QoD session was originally created with duration 30,000 seconds. Before the session expires, the developer requests to extend the session by another 30,000 seconds:
         - Previous duration: 30,000 seconds
-        - Requested additional duration: 30,000 seconds 
+        - Requested additional duration: 30,000 seconds
         - New overall session duration: 50,000 seconds (the maximum allowed)
       operationId: extendQosSessionDuration
       parameters:
@@ -525,9 +525,9 @@ components:
               $ref: "#/components/schemas/SessionId"
             duration:
               description: |
-                Session duration in seconds. Implementations can grant the requested session duration or set a different duration, based on network policies or conditions. 
+                Session duration in seconds. Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
                 - When `qosStatus` is "REQUESTED", the value is the duration to be scheduled, granted by the implementation.
-                - When `qosStatus` is AVAILABLE", the value is the overall duration since `startedAt. When the session is extended, the value is the new overall duration of the session. 
+                - When `qosStatus` is AVAILABLE", the value is the overall duration since `startedAt. When the session is extended, the value is the new overall duration of the session.
                 - When `qosStatus` is "UNAVAILABLE", the value is the overall effective duration since `startedAt` until the session was terminated.
               type: integer
               format: int32
@@ -569,7 +569,7 @@ components:
           properties:
             duration:
               description: |
-                Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the [Qos Profile API](TBC). Implementations can grant the requested session duration or set a different duration, based on network policies or conditions. 
+                Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the [Qos Profile API](TBC). Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
               type: integer
               format: int32
               minimum: 1

From cf9e2967d577a72f14924c03ba7c383089d0d367 Mon Sep 17 00:00:00 2001
From: Jose Luis Urien <joseluis.urienpinedo@telefonica.com>
Date: Thu, 13 Jun 2024 16:44:33 +0200
Subject: [PATCH 3/4] Make + prefix mandatory for phoneNumber

---
 code/API_definitions/quality-on-demand.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml
index 5363730a65..eb1954d9bd 100644
--- a/code/API_definitions/quality-on-demand.yaml
+++ b/code/API_definitions/quality-on-demand.yaml
@@ -771,11 +771,11 @@ components:
       example: "123456789@domain.com"
 
     PhoneNumber:
-      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
+      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
       type: string
-      pattern: '^\+?[0-9]{5,15}$'
-      example: "123456789"
-
+      pattern: '^\+[1-9][0-9]{4,14}$'
+      example: "+123456789"
+      
     DeviceIpv4Addr:
       type: object
       description: |

From 8b969aa81c2135e9e6c6ada99382b107f0968762 Mon Sep 17 00:00:00 2001
From: Jose Luis Urien <joseluis.urienpinedo@telefonica.com>
Date: Thu, 13 Jun 2024 20:58:24 +0200
Subject: [PATCH 4/4] Making the linter happy

---
 code/API_definitions/quality-on-demand.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/API_definitions/quality-on-demand.yaml b/code/API_definitions/quality-on-demand.yaml
index eb1954d9bd..842ed17106 100644
--- a/code/API_definitions/quality-on-demand.yaml
+++ b/code/API_definitions/quality-on-demand.yaml
@@ -775,7 +775,7 @@ components:
       type: string
       pattern: '^\+[1-9][0-9]{4,14}$'
       example: "+123456789"
-      
+
     DeviceIpv4Addr:
       type: object
       description: |