Merge pull request #66 from maheshc01/main

test cases and additional documentation updates
camaraproject · Aug 9, 2024 · 3a84abe · 3a84abe
2 parents 022bd9c + e6506e2
commit 3a84abe
Show file tree

Hide file tree

Showing 10 changed files with 236 additions and 60 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,58 @@
+# Changelog Connectivity Insights
+
+NOTE:
+
+## Table of contents
+
+- [r1.1 - rc]
+
+**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.**
+
+The below sections record the changes for each API version in each (pre-)release as follows:
+
+* for the first alpha or release-candidate API version, all changes since the release of the previous public API version
+* for subsequent alpha or release-candidate API versions, the delta with respect to the previous pre-release
+* for a public API version, the consolidated changes since the release of the previous public API version
+
+
+## Release Notes
+
+This release contains the definition and documentation of
+* Connectivity Insights API
+* Application Profiles API
+
+The API definition(s) are based on
+* Commonalities v0.4.0-rc.1
+* Identity and Consent Management v0.2.0-rc.1
+
+
+## Connectivity Insights API v0.4.0-rc.1
+
+** 0.4.0-rc.1 is the first release-candidate version for connectivity insights**
+
+
+### Main changes
+- This version is primarily to align with the changes to Commonalities 0.4-rc.1 and Identity and Consent Management v0.2.0-rc.1.
+
+- API definition **with inline documentation**:
+  - View it on ReDoc:
+    - [connectivity-insights.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights.yaml&nocors)
+
+    - [application-profiles.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/application-profiles.yaml&nocors)
+  - [View it on Swagger Editor]
+    - [connectivity-insights.yaml]((https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights.yaml))
+      - [application-profiles.yaml]((https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/application-profiles.yaml))
+  - OpenAPI
+    -  [connectivity-insights.yaml](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights.yaml)
+    -  [application-profiles.yaml](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/application-profiles.yaml)
+
+### Added
+  - Gherkin `.feature` file in Test_definitions
+  - Implementation of ICM consent guidelines
+  - Addition of `x-camara-commonalities` object to YAML
+  - Documentation: added warning about use of `networkAccessIdentifier`, added User Story
+
+### Changed
+  - Compliance with DeviceIdentifier schema
+  - Error model alignment, including device identifier-related errors
+  - Updated the API Readiness Checklist to the new format
diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml
@@ -2,13 +2,15 @@ openapi: 3.0.3
 info:
   title: Connectivity Insights - Application Profiles
   version: 0.3.0-rc.1
+  contact:
+    email: [email protected]
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
   description: |
     Application profiles allows application developers to share all the
-    information about their application which would be relavant in
-    network/CAMARA APIs related decision making.  //todo
+    information about their application which would be relevant for network/
+    CAMARA APIs related decision making.
   x-camara-commonalities: 0.4.0
 
 servers:
@@ -49,7 +51,7 @@ paths:
         required: true
       responses:
         "200":
-          description: good
+          description: OK
           content:
             application/json:
               schema:

diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml
@@ -2,63 +2,80 @@ openapi: 3.0.3
 info:
   title: Connectivity Insights
   version: "0.4.0-rc.1"
+  contact:
+    email: [email protected]
   x-camara-commonalities: 0.4.0
   description: |
-    The Connectivity Insights API allows an application developer to ask
-     the network the likelihood that an application's networking
-     requirements can be met for a given end user session.
+    With CAMARA Connectivity Insights, application developers gain essential
+    visibility into network quality. This enables them to make informed
+    decisions that enhance the end-user experience for their applications.
 
-    This information helps a developer ensure their end users are able to
-     get the best experience while using the application over their current
+    # Introduction
+      The Connectivity Insights API allows an application developer to ask
+      the network the likelihood that an application's networking
+      requirements can be met for a given end user session.
+
+      This information helps a developer ensure their end users are able to
+      get the best experience while using the application over their current
       network.
 
-    Depending on the answer the network gives, the developer may decide to
-     request a network boost (via the CAMARA QoD API) , and/or apply
+      Depending on the answer the network gives, the developer may decide to
+      request a network boost (via the CAMARA QoD API) , and/or apply
       specific changes on the application side e.g. adjusting the
       resolution of the video stream upwards or downwards.
 
-    # Introduction
-
 
     # Relevant terms and definitions
 
-    * **Identifier for the device**:
-    At least one identifier for the device (user equipment) out of four
-     options: IPv4 address, IPv6 address, Phone number, or Network Access
-      Identifier assigned by the mobile network operator for the device.
+      * **Identifier for the device**:
+        At least one identifier for the device (user equipment) out of four
+         options: IPv4 address, IPv6 address, Phone number, or Network Access
+          Identifier assigned by the mobile network operator for the device.
 
-    * **Identifier for the application server**:
-    IPv4 and/or IPv6 address of the application server (application backend)
+      * **Identifier for the application server**:
+        IPv4 and/or IPv6 address of the application server
+        (application backend)
 
-    * **Notification URL and token**:
-    Developers may provide a callback URL on which notifications can be
-     received from the service provider. This is an optional parameter.
+      * **Notification URL and token**:
+        Developers may provide a callback URL on which notifications can be
+         received from the service provider. This is an optional parameter.
 
     # API functionality
 
 
-    Following diagram shows the interaction between different components
-    (**editor note paths need to be updated**)
-    ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/main/documentation/API_documentation/sequenceDiagram.v1.png)
-
-    # Authorization and authentication
-
-    CAMARA guidelines defines a set of authorization flows which can grant API
-    clients access to the API functionality, as outlined in the document
-    [CAMARA-API-access-and-user-consent.md]
-    (https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md).
-    Which specific authorization flows are to be used will be determined during
-    onboarding process, happening between the API Client and the Telco Operator
-    exposing the API, taking into account the declared purpose for accessing
-    the API, while also being subject to the prevailing legal framework
-    dictated by local legislation.
-
-    It is important to remark that in cases where personal user data is
-    processed by the API, and users can exercise their rights through
-    mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens
-    becomes mandatory. This measure ensures that the API remains in strict
-    compliance with user privacy preferences and regulatory obligations,
-    upholding the principles of transparency and user-centric data control.
+      Following diagram shows the interaction between different components
+      ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/main/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png)
+
+    ### Notification callback
+
+      This endpoint describes the event notification received on subscription
+      listener side when the event occurred. As for subscription, detailed
+      description of the event notification is provided in the CAMARA API design guideline document.
+
+      **WARNING**: This callback endpoint must be exposed on the listener
+      side as `POST /{$request.body#/sink}`will be posted by the
+      connectivity insights resource server to the webhook url provided
+      by notification listener.
+
+    # Authorization and Authentication
+
+      [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/
+      CAMARA-Security-Interoperability.md) provides details on how a client requests an access token.
+
+      Which specific authorization flows are to be used will be determined
+      during onboarding process, happening between the API Client and the Telco
+      Operator exposing the API, taking into account the declared purpose for
+      accessing the API, while also being subject to the prevailing legal
+      framework dictated by local legislation.
+
+      It is important to remark that in cases where personal user data is
+      processed by the API, and users can exercise their rights through
+      mechanisms such as opt-in and/or opt-out, the use of 3-legged access
+      tokens becomes mandatory. This measure ensures that the API remains in
+      strict compliance with user privacy preferences and regulatory
+      obligations, upholding the principles of transparency and user-centric
+      data control.
+
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -109,17 +126,20 @@ paths:
           defined in the application profile can be met for the particular
           connected device.
         content:
-          "*/*":
+          application/json:
             schema:
               $ref: "#/components/schemas/NetworkQualityInsightRequest"
         required: true
       responses:
         "200":
           description: OK
+          headers:
+            x-correlator:
+              $ref: "#/components/headers/x-correlator"
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/NetworkQualityInsight"
+                $ref: "#/components/schemas/NetworkQualityInsightResponse"
 
   /network-quality/insights/subscriptions:
     post:
@@ -430,7 +450,7 @@ components:
             type: string
         config:
           $ref: "#/components/schemas/Config"
-        id:
+        subscriptionId:
           type: string
           description: |
             The unique identifier of the subscription in the scope of the
@@ -492,7 +512,7 @@ components:
         (Creation or Deletion)
       type: object
       properties:
-        id:
+        subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
 
     SubscriptionId:
@@ -846,16 +866,32 @@ components:
         config:
           $ref: "#/components/schemas/Config"
 
+    NetworkQualityInsightResponse:
+      type: object
+      description: the network's confidence level at being able to meet the
+        network demands of a given policy for a given terminal device.
+      properties:
+        packetDelayBudget:
+          $ref: '#/components/schemas/PolicyFulfillmentConfidence'
+        targetMinDownstreamRate:
+          $ref: '#/components/schemas/PolicyFulfillmentConfidence'
+        targetMinUpstreamRate:
+          $ref: '#/components/schemas/PolicyFulfillmentConfidence'
+        packetlossErrorRate:
+          $ref: '#/components/schemas/PolicyFulfillmentConfidence'
+        jitter:
+          $ref: '#/components/schemas/PolicyFulfillmentConfidence'
+        additionalKPIs:
+          $ref: '#/components/schemas/AdditionalKpis'
+
     NetworkQualityInsight:
       type: object
       description: |
         the network's confidence level at being able to meet the network
         demands of a given policy for a given terminal device.
       properties:
-        policyId:
-          type: string
-          description: Identifier for the policy
-          format: uuid
+        papplicationProfileId:
+          $ref: "#/components/schemas/ApplicationProfileId"
         packetDelayBudget:
           $ref: "#/components/schemas/PolicyFulfillmentConfidence"
         targetMinDownstreamRate:

diff --git a/code/Test_definitions/application-profiles.feature b/code/Test_definitions/application-profiles.feature
@@ -0,0 +1,36 @@
+
+Feature: Application Profiles API automated test
+
+  Background:
+    Given an environment at "apiRoot"
+    And the resource "{path_resource}"
+    And the header "Content-Type" is set to "application/json"
+    And the header "Authorization" is set to a valid access token
+    And the header "x-correlator" is set to a UUID value
+
+  @applicationProfile_create_1_success
+  Scenario: Create application profile
+    Given the API Client makes a POST request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200 OK
+    And The response body complies with ApplicationProfileId object
+
+   @applicationProfile_retrieveById_1_success
+  Scenario: Retrieve details based on specific Id
+    Given the API Client makes a GET request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200 OK
+    And The response body complies with ApplicationProfile object
+
+    @applicationProfile_updateApplicationProfileById_1_success
+  Scenario: Update details based on specific ApplicationProfileId
+    Given the API Client makes a PUT request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200 OK
+    And The response body complies with ApplicationProfile object
+
+  @applicationProfile_deleteById_1_success
+  Scenario: Delete specific ApplicationProfileId
+    Given the API Client makes a DELETE request to the {path_resource}
+    When Create request with the mandatory parameters
+    Then Response code is 200
diff --git a/code/Test_definitions/connectivity-insights.feature b/code/Test_definitions/connectivity-insights.feature
@@ -0,0 +1,44 @@
+
+Feature: Connectivity Insights API automated test
+
+  Background:
+    Given an environment at "apiRoot"
+    And the resource "{path_resource}"
+    And the header "Content-Type" is set to "application/json"
+    And the header "Authorization" is set to a valid access token
+    And the header "x-correlator" is set to a UUID value
+
+  @connectivityInsights_getInsights_1_success
+  Scenario: Retrieve connectivity insights
+    Given The API Client makes a POST request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200 OK
+    And The response body complies with NetworkQualityInsightResponse object
+
+  @connectivityInsights_createSubscription_1_success
+  Scenario: Create subscription for reciving connectivity insghts notifications
+    Given the API Client makes a POST request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 201 Created
+    And The response body complies with Subscription object
+
+  @connectivityInsights_retrieveAllSubscriptions_1_success
+  Scenario: Retrieve all subscriptions details
+    Given the API Client makes a GET request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200
+    And The response body complies with Subscription object
+
+  @connectivityInsights_retrieveSubscriptionById_1_success
+  Scenario: Retrieve subscription details based on specific Id
+    Given the API Client makes a GET request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 200
+    And The response body complies with Subscription object
+
+  @connectivityInsights_deleteSubscriptionById_1_success
+  Scenario: Delete subscription details based on specific Id
+    Given the API Client makes a DELETE request to the {path_resource}
+    When Create request with valid request body
+    Then Response code is 202
+    And The response body complies with SubscriptionAsync object
diff --git a/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md b/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md
@@ -5,17 +5,17 @@ Checklist for connectivity-insights v0.4.0-rc.1
 | Nr | API release assets  | alpha | release-candidate |  initial<br>public | stable<br> public | Status | Comments |
 |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|----|
 |  1 | API definition                               |   M   |         M         |    M    |    M   | Y    | /code/API_definitions/CAMARA Connecitvitity Insights API.yaml |
-|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   | tbd  |      |
+|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   | Y  |      |
 |  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   | Y    |      |
 |  4 | API versioning convention applied            |   M   |         M         |    M    |    M   | Y    |      |
 |  5 | API documentation                            |   M   |         M         |    M    |    M   | Y    | inline in YAML |
-|  6 | User stories                                 |   O   |         O         |    O    |    M   | ?    | /documentation/API_documentation/ConnectivityInsights-User-Story.md |
-|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   | tbd  |  |
+|  6 | User stories                                 |   O   |         O         |    O    |    M   | Y    | /documentation/API_documentation/ConnectivityInsights-User-Story.md |
+|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   | Y  |  |
 |  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   | N    |  |
 |  9 | Test result statement                        |   O   |         O         |    O    |    M   | N    |      |
 | 10 | API release numbering convention applied     |   M   |         M         |    M    |    M   | Y    |      |
-| 11 | Change log updated                           |   M   |         M         |    M    |    M   | tbd  |  |
-| 12 | Previous public release was certified        |   O   |         O         |    O    |    M   | ?    |      |
+| 11 | Change log updated                           |   M   |         M         |    M    |    M   | Y  |  |
+| 12 | Previous public release was certified        |   O   |         O         |    O    |    M   | N    |      |
 
 To fill the checklist:
 - in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release.

diff --git a/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png b/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png