Merge branch 'main' into update-scope

camaraproject · Mar 11, 2024 · 2de1a40 · 2de1a40
2 parents 6ce25a2 + 9d72c4b
commit 2de1a40
Show file tree

Hide file tree

Showing 4 changed files with 133 additions and 34 deletions.
diff --git a/.openapirc.yml b/.openapirc.yml
@@ -23,4 +23,4 @@ rules:
     then:
       function: pattern
       functionOptions:
-        match: ^[0-9]+\.[0-9]+\.[0-9]+(?:-rc|-wip)?$
+        match: ^[0-9]+\.[0-9]+\.[0-9]+(?:-rc|-rc2|-wip)?$
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## Table of Contents
 
+- **[v0.10.0](#v0100)**
+- [v0.10.0-rc2](#v0100-rc2)
 - [v0.10.0-rc](#v0100-rc)
 - [v0.9.0](#v090)
 - [v0.9.0-rc](#v090-rc)
@@ -13,14 +15,86 @@ Version numbers 0.2.x to 0.7.x were intentionally not used to avoid conflicts wi
 
 **Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.**
 
+# v0.10.0
+
+**This release contains the fourth alpha version of the Quality-On-Demand (QoD) API.**
+
+- API definition **with inline documentation**:
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0/code/API_definitions/qod-api.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0/code/API_definitions/qod-api.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/release-0.10.0/code/API_definitions/qod-api.yaml)
+
+### Please note:
+
+- **This release contains significant changes compared to v0.9.0, and the QoD API is not backward compatible**
+  - Within notifications the schema `EventNotification`has been replace by `CloudEvent` in accordance with the updated CAMARA Design Guidelines
+  - If within `device` an IPv6 address is used it must be a single IPv6 address (out of the prefix used by the device)
+- This release includes changes to be compliant with the [Design Guidelines](https://github.com/camaraproject/Commonalities/blob/release-0.2.0/documentation/API-design-guidelines.md#10-security) and other documents in [release v0.2 of CAMARA Commonalities](https://github.com/camaraproject/Commonalities/tree/release-0.2.0)
+- This is another v0.x release and further releases before the first stable major v1.x release might introduce breaking changes (e.g. API changes to align with Commonalities updates)
+
+### Main Changes
+
+* Aligned event notification with CloudEvent spec which will allow API consumers and implementators to use standard libraries and tools which are available to handle CloudEvents (https://cloudevents.io/)
+* Added a new operation `/sessions/{sessionId}/extend` which allows to extend the duration of an active session 
+
+### Added
+
+* Added new endpoint to extend duration of an active session by @emil-cheung in https://github.com/camaraproject/QualityOnDemand/pull/216
+* Introduced of linting with Megalinter and Swagger Editor Validator by @RandyLevensalor, @maxl2287 and @ravindrapalaskar17 in https://github.com/camaraproject/QualityOnDemand/pull/206, https://github.com/camaraproject/QualityOnDemand/pull/207, https://github.com/camaraproject/QualityOnDemand/pull/212, and  https://github.com/camaraproject/QualityOnDemand/pull/215
+* Added global tags element  by @rartych in https://github.com/camaraproject/QualityOnDemand/pull/227
+* Added a new error example for DurationOutOfRangeForQoSProfile by @jlurien in https://github.com/camaraproject/QualityOnDemand/pull/259
+
+### Changed
+
+* Align event notification with CloudEvents spec by @jlurien in https://github.com/camaraproject/QualityOnDemand/pull/224
+* Moved "description" out of "allOf" declaration by @maxl2287 in https://github.com/camaraproject/QualityOnDemand/pull/205
+  * Note: this change shouldn't have an impact for API consumers but is relevant for implementations of the API.
+* Single IP addresses in Device model specified with standard formats instead of patterns by @jlurien in https://github.com/camaraproject/QualityOnDemand/pull/237
+* Moved "basePath" /qod/v0 to "url"-property and introduced "apiroot" in definition of server  @maxl2287 in https://github.com/camaraproject/QualityOnDemand/pull/252
+* Added statusInfo 'DELETE_REQUESTED' for qosStatus 'UNAVAILABLE' and clarified notification events in documentation by @hdamker in https://github.com/camaraproject/QualityOnDemand/pull/258
+
+### Fixed
+
+* NA
+
+### Removed
+
+* NA
+
+## New Contributors
+* @ravindrapalaskar17 made their first contribution in https://github.com/camaraproject/QualityOnDemand/pull/215
+* @rartych made their first contribution in https://github.com/camaraproject/QualityOnDemand/pull/227
+
+**Full Changelog**: https://github.com/camaraproject/QualityOnDemand/compare/v0.9.0...v0.10.0
+
+# v0.10.0-rc2
+
+**This is the second release candidate of v0.10.0 - containing the upcoming fourth alpha version of the Quality-On-Demand (QoD) API**
+
+- API definition **with inline documentation**:
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/v0.10.0-rc2/code/API_definitions/qod-api.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/v0.10.0-rc2/code/API_definitions/qod-api.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/v0.10.0-rc2/code/API_definitions/qod-api.yaml)
+
+## Changes compared to [v0.10.0-rc](#v0100-rc)
+
+* Added a new error example for DurationOutOfRangeForQoSProfile by @jlurien in https://github.com/camaraproject/QualityOnDemand/pull/259
+* Moved "basePath" /qod/v0 to "url"-property and introduced "apiroot" in definition of server  @maxl2287 in https://github.com/camaraproject/QualityOnDemand/pull/252
+* Added a note to maxDuration parameter within qosProfile schema about the limit of 86400 seconds by @hdamker in https://github.com/camaraproject/QualityOnDemand/pull/256
+* Added statusInfo 'DELETE_REQUESTED' for qosStatus 'UNAVAILABLE' and clarified notification events in documentation by @hdamker in https://github.com/camaraproject/QualityOnDemand/pull/258:
+  * notifications will be sent for all changes of QosStatus, even if initiated by the client.
+  * what will happen when qosStatus changes from 'AVAILABLE' to 'UNAVAILABLE' due to 'NETWORK_TERMINATED'
+
+**Full Changelog**: https://github.com/camaraproject/QualityOnDemand/compare/v0.10.0-rc...v0.10.0-rc2
+
 # v0.10.0-rc
 
-**This is the release candidate of v0.10.0 - containing the upcoming fourth alpha version of the Quality-On-Demand (QoD) API**
+**This is the first release candidate of v0.10.0 - containing the upcoming fourth alpha version of the Quality-On-Demand (QoD) API**
 
 - API definition **with inline documentation**:
-  - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/release-0.10.0-rc/code/API_definitions/qod-api.yaml)
-  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0-rc/code/API_definitions/qod-api.yaml&nocors)
-  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0-rc/code/API_definitions/qod-api.yaml)
+  - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/v0.10.0-rc/code/API_definitions/qod-api.yaml&nocors)
+  - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/v0.10.0-rc/code/API_definitions/qod-api.yaml)
+  - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/v0.10.0-rc/code/API_definitions/qod-api.yaml)
 
 ## Please note:
 

diff --git a/README.md b/README.md
@@ -28,23 +28,17 @@ Repository to describe, develop, document and test the QualityOnDemand API famil
 
 * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
 
-* **The Release Candidate for v0.10.0 of the Quality-On-Demand API is available. This upcoming release will contain the fourth alpha version of the QoD API**<br>Until the release there are bug fixes to be expected. The release candidate is suitable for implementors, but it is not recommended to use the API with customers in productive environments.
-* The release candidate for v0.10.0 is available in the [release-0.10.0-rc branch](https://github.com/camaraproject/QualityOnDemand/tree/release-0.10.0-rc)
-  - API definition v0.10.0-rc with inline documentation:
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0-rc/code/API_definitions/qod-api.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0-rc/code/API_definitions/qod-api.yaml)
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/release-0.10.0-rc/code/API_definitions/qod-api.yaml)
-  - For changes between v0.10.0-rc and v0.9.0 see the [CHANGELOG.md](https://github.com/camaraproject/QualityOnDemand/blob/main/CHANGELOG.md)
-
-* The latest available and released version 0.9.0 is available within the [release-0.9.0 branch](https://github.com/camaraproject/QualityOnDemand/tree/release-0.9.0)
-  - API definition v0.9.0 with inline documentation:
-    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.9.0/code/API_definitions/qod-api.yaml&nocors)
-    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.9.0/code/API_definitions/qod-api.yaml)
-    - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/release-0.9.0/code/API_definitions/qod-api.yaml)
-
-* The previous released version v0.8.1 is availabe within the [release-0.8.1 branch](https://github.com/camaraproject/QualityOnDemand/tree/release-0.8.1)
-
-* Provider implementations (PI) are available within separate repositories:
+* **The latest available and released version 0.10.0 is available within the [release-0.10.0 branch](https://github.com/camaraproject/QualityOnDemand/tree/release-0.10.0)**
+  - API definition v0.10.0 with inline documentation:
+    - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0/code/API_definitions/qod-api.yaml&nocors)
+    - [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.10.0/code/API_definitions/qod-api.yaml)
+    - OpenAPI [YAML spec file](https://github.com/camaraproject/QualityOnDemand/blob/release-0.10.0/code/API_definitions/qod-api.yaml)
+
+* The previous released version v0.9.0 is availabe within the [release-0.9.0 branch](https://github.com/camaraproject/QualityOnDemand/tree/release-0.9.0)
+* For changes between v0.10.0 and v0.9.0 see the [CHANGELOG.md](https://github.com/camaraproject/QualityOnDemand/blob/main/CHANGELOG.md)
+
+* Provider implementations (PI) are available within separate repositories (partly for previous releases):
+
   * [QualityOnDemand_PI1](https://github.com/camaraproject/QualityOnDemand_PI1) by Deutsche Telekom
   * [QualityOnDemand_PI2](https://github.com/camaraproject/QualityOnDemand_PI2) by Orange
   * [QualityOnDemand_PI3](https://github.com/camaraproject/QualityOnDemand_PI3) by Spry Fox Networks

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
 
@@ -66,21 +66,18 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.10.0-rc
+  version: 0.10.0
 externalDocs:
   description: Product documentation at Camara
   url: https://github.com/camaraproject/
 security:
   - oAuth2ClientCredentials: []
 servers:
-  - url: "{apiRoot}/{basePath}"
+  - url: "{apiRoot}/qod/v0"
     variables:
       apiRoot:
         default: http://localhost:9091
-        description: API root
-      basePath:
-        default: qod/v0
-        description: Base path for the QoD API
+        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
 tags:
   - name: QoS Sessions
     description: Manage QoS sessions
@@ -92,7 +89,24 @@ 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 qosStatus in the API response is "AVAILABLE" and a notification callback is provided the client will receive in addition to the response a
+        `QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE`.
+
+        If the `qosStatus` in the API response is `REQUESTED`, the client will receive either
+        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as `AVAILABLE` after the network notifies that it has created the requested session, or
+        - a `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` after the network notifies that it has failed to provide the requested session.
+
+        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.
+        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.
+
       operationId: createSession
       requestBody:
         description: Parameters to create a new session
@@ -110,7 +124,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:
@@ -206,6 +220,12 @@ paths:
                     status: 400
                     code: OUT_OF_RANGE
                     message: "Invalid port ranges specified: devicePorts"
+                DurationOutOfRangeForQoSProfile:
+                  summary: The requested duration is out of the allowed range for the specific QoS profile
+                  value:
+                    status: 400
+                    code: OUT_OF_RANGE
+                    message: "The requested duration is out of the allowed range for the specific QoS profile"
         "401":
           $ref: "#/components/responses/Generic401"
         "403":
@@ -273,7 +293,13 @@ paths:
       tags:
         - QoS Sessions
       summary: Delete a QoS session
-      description: Free resources related to QoS session
+      description: |
+        Release resources related to QoS session
+
+        If the notification callback is provided and the `qosStatus` of the session was `AVAILABLE` the client will receive in addition to the response a `QOS_STATUS_CHANGED` event with
+        - `qosStatus` as `UNAVAILABLE` and
+        - `statusInfo` as `DELETE_REQUESTED`
+        There will be no notification event if the `qosStatus` was already `UNAVAILABLE`.
       operationId: deleteSession
       parameters:
         - name: sessionId
@@ -687,6 +713,8 @@ 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.
           allOf:
             - $ref: "#/components/schemas/Duration"
         priority:
@@ -887,10 +915,13 @@ 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 +1065,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.
+        *  `UNAVAILABLE` - A requested or previously available QoS session is now unavailable. `statusInfo` may provide additional information about the reason for the unavailability.
       type: string
       enum:
         - AVAILABLE