From d261b6183bd5f3279ff43e16a29fc918156a83b3 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Fri, 9 Aug 2024 16:54:48 +0100 Subject: [PATCH 01/33] Update CHANGELOG.md Fixed some link syntax --- CHANGELOG.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fdcd1d..1be7115 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ NOTE: ## Table of contents -- [r1.1 - rc] +- **[r1.1 - rc](#r11---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.** @@ -14,7 +14,7 @@ The below sections record the changes for each API version in each (pre-)release * 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 - +# r1.1 - rc ## Release Notes This release contains the definition and documentation of @@ -25,7 +25,6 @@ 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** From 027840f1f660a5b02d996b509b9108c29ba0415c Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 12 Aug 2024 15:00:26 +0100 Subject: [PATCH 02/33] docs: add release information to README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1ef9563..2b43d06 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,9 @@ Repository to describe, develop, document and test the Connectivity Insights API ## Release Information - + Pre-releases of this sub project are available in https://github.com/camaraproject/ConnectivityInsights/releases - +For changes see [CHANGELOG.md](https://github.com/camaraproject/ConnectivityInsights/blob/main/CHANGELOG.md) ## Contributing * Meetings From 2564a8c6960725e9ea3539b92db3e0a87ebe3e49 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 12 Aug 2024 16:55:50 +0100 Subject: [PATCH 03/33] docs: add feature links --- .../Connectivity-Insights-API-Readiness-Checklist.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md b/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md index cd8ec85..e87b4e2 100644 --- a/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md +++ b/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md @@ -9,8 +9,8 @@ Checklist for connectivity-insights v0.4.0-rc.1 | 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 | Y | /documentation/API_documentation/ConnectivityInsights-User-Story.md | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | | +| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/ConnectivityInsights-User-Story.md) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/connectivity-insights.feature) | | 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 | | From 1a430b677783da88e0650cac56538d3751e9f0fc Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 12 Aug 2024 16:58:02 +0100 Subject: [PATCH 04/33] docs: fix link to API definition --- .../Connectivity-Insights-API-Readiness-Checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md b/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md index e87b4e2..c3f1d64 100644 --- a/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md +++ b/documentation/API_documentation/Connectivity-Insights-API-Readiness-Checklist.md @@ -4,7 +4,7 @@ Checklist for connectivity-insights v0.4.0-rc.1 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|----| -| 1 | API definition | M | M | M | M | Y | /code/API_definitions/CAMARA Connecitvitity Insights API.yaml | +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/connectivity-insights.yaml) | | 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 | | From ef79297e80c0e2850ea894225dfbdc6b7b13db62 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 12 Aug 2024 17:00:22 +0100 Subject: [PATCH 05/33] docs: add links to test feature files --- .../application-profiles-API-Readiness-Checklist.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md b/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md index fb60794..077d176 100644 --- a/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md +++ b/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md @@ -4,13 +4,13 @@ Checklist for application-profile v0.3.0-rc.1 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|----| -| 1 | API definition | M | M | M | M | Y | /code/API_definitions/application-profiles.yaml | +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/application-profiles.yaml) | | 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 | Y | /documentation/API_documentation/ConnecitivityInsights-User-Story.md | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | | +| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/ConnectivityInsights-User-Story.md) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/application-profiles.feature) | | 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 | | From c2fcfdda94a08c09ed4a23fde1d66ce74c327dc6 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Mon, 12 Aug 2024 17:19:38 +0100 Subject: [PATCH 06/33] docs: add application-profiles changelog --- CHANGELOG.md | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1be7115..72d3bf9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,13 +37,13 @@ The API definition(s) are based on - 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)) + + - 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) + - 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 @@ -55,3 +55,37 @@ The API definition(s) are based on - Compliance with DeviceIdentifier schema - Error model alignment, including device identifier-related errors - Updated the API Readiness Checklist to the new format + +## Application Profiles API 0.3.0-rc.1 + + + +** 0.3.0-rc.1 is the first release-candidate version for application profile.** + + + +### 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: + - [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 + - [application-profiles.yaml](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/application-profiles.yaml) + + - OpenAPI + - [application-profiles.yaml](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/application-profiles.yaml) + +### Added + +- Gherkin +`.feature` file in Test_definitions + +### Changed + +- Aligned the network monitoring KPIs to match with Quality on Demand CAMARA API. +- update the end points to make it more developer friendly based on the discussion in the API working group. +- Updated the API Readiness Checklist to the new format + From fedf4965cafd13500e611c187b6048161548a582 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Wed, 14 Aug 2024 17:13:19 +0100 Subject: [PATCH 07/33] Update connectivity-insights.yaml Fixes: #68 #69 #70 #71 #72 #73 --- .../connectivity-insights.yaml | 1104 +++++------------ 1 file changed, 283 insertions(+), 821 deletions(-) diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index 65af53a..330c2a2 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -1,9 +1,7 @@ openapi: 3.0.3 info: title: Connectivity Insights - version: "0.4.0-rc.1" - contact: - email: sp-coi@lists.camaraproject.org + version: 0.4.0-rc.1 x-camara-commonalities: 0.4.0 description: | With CAMARA Connectivity Insights, application developers gain essential @@ -25,42 +23,60 @@ info: resolution of the video stream upwards or downwards. - # 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 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. - # API functionality + Prerequisite: authorisation and authentication + + Usage: + 1. create an application profile using the Connectivity Insights + `application-profiles` API + 2. Request: POST `check-network-quality`, passing the + `applicationProfileId` obtained in step 1, the address/port of an + application server, and at least one device identifier. + 3. Response: The network will indicate whether it can or cannot meet + the application requirements. + 3. Optional: use the `connectivity-insights-subscriptions` API to receive + notifications of network quality. + + todo: sequence diagram + + # Identifying the device + + This can be achieved either by passing at least one device identifier in + the POST request body, or, from the 3-legged access token where implemented + by the operator. + + Device identifiers in POST request body: + * `IPv4-Address` or `IPv6-Address`. This is the public IP address of the + user device: this + can be obtained by an application hosted on that device calling a + public IP address API (e.g. GET https://api.ipify.org?format=json) + * If you provide an `IPv4-Address` or `IPv6-Address`: for certain + operators you may be required to also provide a `Public-port` header. + * `Phone-Number` . The international E.164 format (starting with country + code), e.g. +4407123123456 + * `Network-Access-Identifier` (where available from the API host + operator) + + NOTE1: the network operators might support only a subset of these options. + The API invoker can provide multiple identifiers to be compatible across + different network operators. In this case the identifiers MUST belong to + the same device. + + NOTE2: for the Commonalities release v0.4, we are enforcing that the + `networkAccessIdentifier` is only part of the schema for future-proofing, + and CAMARA does not currently allow its use. After the CAMARA meta-release + work is concluded and the relevant issues are resolved, its use will need to + be explicitly documented in the guidelines. - 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. + The "Camara Security and Interoperability Profile" provides details on + how a client requests an access token. Please refer to + Identify and Consent Management + (https://github.com/camaraproject/IdentityAndConsentManagement/) for the + released version of the Profile. Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco @@ -94,31 +110,25 @@ servers: `api.example.com` or `api.example.com/somepath` tags: - - name: Quality Insights + - name: Network Quality description: | Read the network's level of confidence that it can meet the quality thresholds for a given application profile and end user device. - - name: Connectivity Insights Subscriptions - description: | - Create and manage a subscription to receive periodic connectivity - insights paths: - /network-quality/insights: + /check-network-quality: post: security: - openId: - - connectivity_insights:network_quality_insight:write + - connectivity-insights:check tags: - - Quality Insights - summary: Create an insight + - Network Quality + summary: Check the network quality. description: | - Create an insight. The response shows the network's current level - of confidence that it can meet an application profile's quality - thresholds for a given end user device. An `insightId` is included - to support polling via the GET operation, or to requrest callbacks - via the Notification Management operations. - operationId: createNetworkQualityInsight + Check the network quality. The response shows the network's current + level of confidence that it can meet an application profile's quality + thresholds for a given end user device. + operationId: checkNetworkQuality requestBody: description: | An `ApplicationProfileId` and one or more device identifiers. @@ -141,389 +151,18 @@ paths: schema: $ref: "#/components/schemas/NetworkQualityInsightResponse" - /network-quality/insights/subscriptions: - post: - tags: - - Connectivity Insights Subscriptions - description: "Create a Connectivity insights subscription for a device" - summary: "Create a Connectivity insights subscription for a device" - operationId: createSubscription - parameters: - - $ref: "#/components/parameters/x-correlator" - security: - - openId: - - connectivity_insights:subscriptions:write - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/SubscriptionRequest" - required: true - callbacks: - notifications: - "{$request.body#/sink}": - post: - summary: "Subscription notification callback" - description: | - Important: this endpoint is to be implemented by the API - consumer.The Connectivity Insights server will call this - endpoint whenever a connectivity event occurs that changes - the netowrk's ability to meet the application's demands for - a given device. - operationId: postNotification - parameters: - - $ref: "#/components/parameters/x-correlator" - requestBody: - required: true - content: - application/cloudevents+json:: - schema: - $ref: "#/components/schemas/CloudEvent" - - responses: - "204": - description: Successful notification - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "410": - $ref: "#/components/responses/Generic410" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - security: - - {} - - notificationsBearerAuth: [] - responses: - "201": - description: Created - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/Subscription" - "202": - description: | - Request accepted to be processed. It applies for async - creation process. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/SubscriptionAsync" - "400": - $ref: "#/components/responses/CreateSubscriptionBadRequest400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/CreateSubscription403" - "409": - $ref: "#/components/responses/Generic409" - "415": - $ref: "#/components/responses/Generic415" - "422": - $ref: "#/components/responses/CreateSubscription422" - "429": - $ref: "#/components/responses/Generic429" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - get: - tags: - - Connectivity Insights Subscriptions - summary: "Retrieve a list of apiName event subscription" - operationId: getSubscriptionList - description: | - Operation to list subscriptions authorized to be retrieved by the - provided access token. - parameters: - - $ref: "#/components/parameters/x-correlator" - security: - - openId: - - connectivity_insights:subscriptions:read - responses: - "200": - description: List of event subscription details - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - type: array - minItems: 0 - items: - $ref: "#/components/schemas/Subscription" - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - /network-quality/insights/subscriptions/{subscriptionId}: - get: - tags: - - Connectivity Insights Subscriptions - summary: "Operation to retrieve a subscription based on the provided ID" - operationId: getSubscription - description: Retrieve a given subscription by ID - security: - - openId: - - connectivity_insights:subscriptions:read - parameters: - - $ref: "#/components/parameters/SubscriptionId" - - $ref: "#/components/parameters/x-correlator" - responses: - "200": - description: OK - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/Subscription" - "400": - $ref: "#/components/responses/SubscriptionIdRequired" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - delete: - tags: - - Connectivity Insights Subscriptions - summary: "Operation to delete a subscription" - operationId: deleteSubscription - description: Delete a given subscription by ID - security: - - openId: - - connectivity_insights:subscriptions:write - parameters: - - $ref: "#/components/parameters/SubscriptionId" - - $ref: "#/components/parameters/x-correlator" - responses: - "204": - description: apiName subscription deleted - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - "202": - description: | - Request accepted to be processed. It applies for async deletion - process. - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/SubscriptionAsync" - "400": - $ref: "#/components/responses/SubscriptionIdRequired" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - components: securitySchemes: openId: description: OpenID Provider Configuration Information type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration - notificationsBearerAuth: - description: Bearer authorization for notifications - type: http - scheme: bearer - bearerFormat: "{$request.body#/sinkCredential.credentialType}" - parameters: - SubscriptionId: - name: subscriptionId - in: path - description: | - Subscription identifier that was obtained from the create event - subscription operation - required: true - schema: - $ref: "#/components/schemas/SubscriptionId" - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - type: string headers: x-correlator: description: Correlation id for the different services schema: type: string - schemas: - AdditionalKpis: - description: additional information about connectivity quality - type: object - properties: - signalStrength: - description: | - rough indication of the end user device radio signal conditions - type: string - enum: - - excellent - - good - - fair - - poor - - no signal - connectivityType: - description: | - the access technology connecting the user device to the operator - network - type: string - enum: - - 5G-SA - - 5G-NSA - - 4G - - 3G - - Subscription: - description: Represents a event-type subscription. - type: object - required: - - sink - - protocol - - config - - types - - id - - startsAt - properties: - protocol: - $ref: "#/components/schemas/Protocol" - sink: - type: string - format: url - description: | - The address to which events shall be delivered using the selected - protocol. - example: "https://endpoint.example.com/sink" - sinkCredential: - $ref: "#/components/schemas/SinkCredential" - types: - description: | - Camara Event types eligible to be delivered by this subscription. - Note: for the Commonalities meta-release v0.4 we enforce to have - only event type per subscription then for following meta-release - use of array MUST be decided at API project level. - type: array - items: - type: string - config: - $ref: "#/components/schemas/Config" - subscriptionId: - type: string - description: | - The unique identifier of the subscription in the scope of the - subscription manager. When this information is contained within - an event notification, this concept SHALL be referred as - `subscriptionId` as per - [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). - example: "1119920371" - startsAt: - type: string - format: date-time - description: Date when the event subscription will begin/began - expiresAt: - type: string - format: date-time - description: | - Date when the event subscription will expire. Only provided when - `subscriptionExpireTime` is indicated by API client or Telco - Operator has specific policy about that. - status: - type: string - description: |- - Current status of the subscription - Management of Subscription - State engine is not mandatory for now. Note not all statuses may - be considered to be implemented. Details: - - `ACTIVATION_REQUESTED`: Subscription creation (POST) is - triggered but subscription creation process is not finished - yet. - - `ACTIVE`: Subscription creation process is completed. - Subscription is fully operative. - - `DEACTIVE`: Subscription is temporarily inactive, but its - workflow logic is not deleted. - - `EXPIRED`: Subscription is ended (no longer active). - This status applies when subscription is ended due to - `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event. - - `DELETED`: Subscription is ended as deleted (no longer - active). This status applies when subscription information is - kept (i.e. subscription workflow is no longer active but its - metainformation is kept). - enum: - - ACTIVATION_REQUESTED - - ACTIVE - - EXPIRED - - DEACTIVE - - DELETED - discriminator: - propertyName: protocol - mapping: - HTTP: "#/components/schemas/HTTPSubscriptionResponse" - MQTT3: "#/components/schemas/MQTTSubscriptionResponse" - MQTT5: "#/components/schemas/MQTTSubscriptionResponse" - AMQP: "#/components/schemas/AMQPSubscriptionResponse" - NATS: "#/components/schemas/NATSSubscriptionResponse" - KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse" - - SubscriptionAsync: - description: | - Response for a event-type subscription request managed asynchronously - (Creation or Deletion) - type: object - properties: - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - - SubscriptionId: - type: string - description: | - The unique identifier of the subscription in the scope of the - subscription manager. When this information is contained within - an event notification, this concept SHALL be referred as - `subscriptionId` as per - [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). - example: qs15-h556-rt89-1298 NetworkQualityInsightRequest: description: | request body to query the network quality for a given device and @@ -541,12 +180,6 @@ components: A list of single ports or port ranges on the application server allOf: - $ref: "#/components/schemas/PortsSpec" - monitoringDataAggregation: - description: frequency of subscription reporting - enum: - - FIFTEEN_MIN - - HOURLY - - DAILY monitoringTimeStamp: type: string format: date-time @@ -556,6 +189,50 @@ components: current date and time is used and network data for the monitoring data aggregation is used to check network performance against the policy defined. + + 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" + + AdditionalKpis: + description: additional information about connectivity quality + type: object + properties: + signalStrength: + description: | + rough indication of the end user device radio signal conditions + type: string + enum: + - excellent + - good + - fair + - poor + - no signal + connectivityType: + description: | + the access technology connecting the user device to the operator + network + type: string + enum: + - 5G-SA + - 5G-NSA + - 4G + - 3G + Device: description: | End-user equipment able to connect to a mobile network. Examples of @@ -643,7 +320,7 @@ components: anyOf: - required: [publicAddress, privateAddress] - required: [publicAddress, publicPort] - example: {"publicAddress":"84.125.93.10", "publicPort":59765} + example: {"publicAddress": "84.125.93.10", "publicPort": 59765} SingleIpv4Addr: description: A single IPv4 address with no subnet mask @@ -703,13 +380,6 @@ components: - 5060 - 5070 - Protocol: - type: string - enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] - description: | - Identifier of a delivery protocol. Only HTTP is allowed for now - example: "HTTP" - ApplicationServer: description: | A server hosting backend applications to deliver some business logic to @@ -730,6 +400,7 @@ components: ipv6Address: $ref: "#/components/schemas/ApplicationServerIpv6Address" minProperties: 1 + ApplicationServerIpv4Address: type: string example: "192.168.0.1/24" @@ -753,157 +424,6 @@ components: - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 - Config: - description: | - Implementation-specific configuration parameters needed by the - subscription manager for acquiring events. - In CAMARA we have predefined attributes like `subscriptionExpireTime`, - `subscriptionMaxEvents`, `initialEvent` - Specific event type attributes must be defined in `subscriptionDetail` - Note: if a request is performed for several event type, all subscribed - event will use same `config` parameters. - type: object - required: - - subscriptionDetail - properties: - subscriptionDetail: - $ref: "#/components/schemas/CreateSubscriptionDetail" - subscriptionExpireTime: - type: string - format: date-time - example: 2023-01-17T13:18:23.682Z - description: | - The subscription expiration time (in date-time format) requested by - the API consumer. Up to API project decision to keep it. - subscriptionMaxEvents: - type: integer - description: | - Identifies the maximum number of event reports to be generated - (>=1) requested by the API consumer - Once this number is reached, - the subscription ends. Up to API project decision to keep it. - minimum: 1 - example: 5 - initialEvent: - type: boolean - description: | - Set to `true` by API consumer if consumer wants to get an event as - soon as the subscription is created and current situation reflects - event request. - Example: Consumer request Roaming event. If consumer sets - initialEvent to true and device is in roaming situation, an event - is triggered Up to API project decision to keep it. - SinkCredential: - type: object - description: | - A sink credential provides authentication or authorization information - properties: - credentialType: - type: string - enum: - - PLAIN - - ACCESSTOKEN - - REFRESHTOKEN - description: "The type of the credential." - discriminator: - propertyName: credentialType - mapping: - PLAIN: "#/components/schemas/PlainCredential" - ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" - REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" - required: - - credentialType - - CreateSubscriptionDetail: - description: The detail of the requested event subscription - type: object - properties: - device: - $ref: "#/components/schemas/Device" - applicationServer: - $ref: "#/components/schemas/ApplicationServer" - applicationServerPorts: - description: | - A list of single ports or port ranges on the application server - allOf: - - $ref: "#/components/schemas/PortsSpec" - applicationProfileId: - $ref: "#/components/schemas/ApplicationProfileId" - required: - - device - - applicationProfileId - - SubscriptionRequest: - description: The request for creating a event-type event subscription - type: object - required: - - sink - - protocol - - config - - types - properties: - protocol: - $ref: "#/components/schemas/Protocol" - sink: - type: string - format: url - description: | - The address to which events shall be delivered using the selected - protocol. - example: "https://endpoint.example.com/sink" - sinkCredential: - $ref: "#/components/schemas/SinkCredential" - types: - description: | - Camara Event types eligible to be delivered by this subscription. - Note: for the Commonalities meta-release v0.4 we enforce to have - only event type per subscription then for following meta-release - use of array MUST be decided at API project level. - type: array - items: - type: string - example: org.camaraproject.connectivityinsights.v0.policy-not-met, - org.camaraproject.connectivityinsights.v0.policy-met - 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: - papplicationProfileId: - $ref: "#/components/schemas/ApplicationProfileId" - 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" PolicyFulfillmentConfidence: type: string @@ -919,125 +439,6 @@ components: type: string format: uuid - Source: - type: string - format: uri-reference - minLength: 1 - description: | - Identifies the context in which an event happened, as a non-empty - `URI-reference` like: - - URI with a DNS authority: - * https://github.com/cloudevents - * mailto:cncf-wg-serverless@lists.cncf.io - - Universally-unique URN with a UUID: - * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - Application-specific identifier: - * /cloudevents/spec/pull/123 - * 1-555-123-4567 - example: "https://notificationSendServer12.supertelco.com" - CloudEvent: - description: The Cloud-Event used for the callback. - required: - - id - - source - - specversion - - type - - time - properties: - id: - type: string - description: | - identifier of this event, that must be unique in the source context. - source: - $ref: "#/components/schemas/Source" - type: - $ref: "#/components/schemas/Event-typeNotification" - specversion: - type: string - description: | - Version of the specification to which this event conforms (must be - 1.0 if it conforms to cloudevents 1.0.2 version) - enum: - - "1.0" - datacontenttype: - type: string - description: | - 'media-type that describes the event payload encoding, - must be "application/json" for CAMARA APIs' - enum: - - application/json - data: - $ref: "#/components/schemas/NetworkQualityInsight" - time: - $ref: "#/components/schemas/DateTime" - discriminator: - propertyName: "type" - mapping: - org.camaraproject.connectivityinsights.v0.networkQuality-event: "#/components/schemas/NetworkQualityTypeEvent" - org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" - - NetworkQualityTypeEvent: - description: event structure for event-type event - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - - EventSubscriptionEnds: - description: event structure for event subscription ends - allOf: - - $ref: "#/components/schemas/CloudEvent" - - type: object - properties: - data: - $ref: "#/components/schemas/SubscriptionEnds" - - SubscriptionEnds: - description: Event detail structure for SUBSCRIPTION_ENDS event - type: object - required: - - terminationReason - - subscriptionId - properties: - terminationReason: - $ref: "#/components/schemas/TerminationReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - terminationDescription: - type: string - - TerminationReason: - type: string - description: | - - NETWORK_TERMINATED - API server stopped sending notification - - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by - the requester) has been reached - - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the - requester) has been reached - - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by - the requester) expiration time has been reached - enum: - - MAX_EVENTS_REACHED - - NETWORK_TERMINATED - - SUBSCRIPTION_EXPIRED - - ACCESS_TOKEN_EXPIRED - - DateTime: - type: string - format: date-time - description: | - Timestamp of when the occurrence happened. Must adhere to RFC 3339. - example: "2018-04-05T17:31:00Z" - - Event-typeNotification: - type: string - description: | - event-type - Event triggered when an event-type event occurred - subscription-ends: Event triggered when the subscription ends - enum: - - org.camaraproject.connectivityinsights.v0.networkQuality-met - - org.camaraproject.connectivityinsights.v0.networkQuality-not-met - - org.camaraproject.connectivityinsights.v0.subscription-ends - ErrorInfo: type: object description: Error information @@ -1057,8 +458,8 @@ components: description: Detailed error description responses: - CreateSubscriptionBadRequest400: - description: Problem with the client request + Generic400: + description: Bad Request headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1067,45 +468,20 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - InvalidArgument: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception value: status: 400 - code: "INVALID_ARGUMENT" - message: | - "Client specified an invalid argument, request body or - query param" - InvalidProtocol: - value: - status: 400 - code: "INVALID_PROTOCOL" - message: "Only HTTP is supported" - InvalidCredential: - value: - status: 400 - code: "INVALID_CREDENTIAL" - message: "Only Access token is supported" - InvalidToken: + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested value: status: 400 - code: "INVALID_TOKEN" - message: "Only bearer token is supported" - Generic400: - description: Problem with the client request - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: "INVALID_ARGUMENT" - message: | - "Client specified an invalid argument, - request body or query param" + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: - description: Authentication problem with the client request + description: Unauthorized headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1113,15 +489,21 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: "UNAUTHENTICATED" - message: | - "Request not authenticated due to missing, invalid, or - expired credentials" - - CreateSubscription403: - description: Client does not have sufficient permission + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + Generic403: + description: Forbidden headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1130,21 +512,20 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PermissionDenied: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 - code: "PERMISSION_DENIED" - message: | - "Client does not have sufficient permissions to perform - this action" - TokenMismatch: + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token value: status: 403 - code: "SUSBCRIPTION_MISMATCH" - message: | - "Inconsistent access token for requested events subscription" - Generic403: - description: Client does not have sufficient permission + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + Generic404: + description: Resource Not Found headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1152,14 +533,21 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: "PERMISSION_DENIED" - message: | - "Client does not have sufficient permissions to perform - this action" - Generic404: - description: Resource Not Found + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. + Generic405: + description: Method Not Allowed headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1167,10 +555,13 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "The specified resource is not found" + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. Generic409: description: Conflict headers: @@ -1180,10 +571,25 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: CONFLICT - message: "The specified resource is in a conflict" + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. Generic410: description: Gone headers: @@ -1193,27 +599,31 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 410 - code: GONE - message: | - "The specified resource is no longer available at the - requested address" + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. Generic415: description: Unsupported Media Type headers: - X-Correlator: + x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: "The specified media type is not supported" - CreateSubscription422: - description: Unprocessable Entity + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: + description: Unprocessable Content headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1222,26 +632,48 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - PermissionDenied: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device value: status: 422 - code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" - message: "Multi event types subscription not managed" + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: The device cannot be identified. Generic429: description: Too Many Requests headers: - X-Correlator: + x-correlator: $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 429 - code: TOO_MANY_REQUESTS - message: "Endpoint does not support as many requests per time slot" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. Generic500: - description: Server error + description: Internal Server Error headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1249,12 +681,31 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: "INTERNAL" - message: "Server error" - Generic503: - description: Service unavailable. Typically the server is down. + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1262,12 +713,15 @@ components: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: "UNAVAILABLE" - message: "Service unavailable" - SubscriptionIdRequired: - description: Problem with the client request + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -1276,17 +730,25 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - Generic400: - summary: Schema validation failed + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side value: - status: 400 - code: INVALID_ARGUMENT - message: | - "Client specified an invalid argument, request body or query - param" - subscriptionIdRequired: - summary: subscription id is required + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId" + status: 504 + code: TIMEOUT + message: Request timeout exceeded. From a23e24544432de670999c33429723c2c46eea6bb Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Thu, 15 Aug 2024 23:56:54 -0500 Subject: [PATCH 08/33] addressing issues as per review comments in #PR 67 --- .../connectivity-insights-subscriptions.yaml | 1265 +++++++++++++++++ .../connectivity-insights.yaml | 196 +-- 2 files changed, 1294 insertions(+), 167 deletions(-) create mode 100644 code/API_definitions/connectivity-insights-subscriptions.yaml diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml new file mode 100644 index 0000000..a496620 --- /dev/null +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -0,0 +1,1265 @@ +openapi: 3.0.3 +info: + title: Connectivity Insights + version: 0.4.0-rc.1 + x-camara-commonalities: 0.4.0 + description: | + 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. + + # 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 + specific changes on the application side e.g. adjusting the + resolution of the video stream upwards or downwards. + + + # 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 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. + + # API functionality + + + 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/r0.2.0-rc.2/ + 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 + +externalDocs: + description: Product documentation at CAMARA. + url: https://github.com/camaraproject/ConnectivityInsights + +servers: + - url: "{apiRoot}/connectivity-insights-subscriptions/v0.4rc1/check-network-quality" + variables: + apiRoot: + default: http://localhost:9091 + description: | + API root, defined by service provider, e.g. + `api.example.com` or `api.example.com/somepath` + +tags: + - name: Connectivity Insights Subscriptions + description: | + Create and manage a subscription to receive periodic connectivity + insights + +paths: + /subscriptions: + post: + tags: + - Connectivity Insights Subscriptions + description: "Create a Connectivity insights subscription for a device" + summary: "Create a Connectivity insights subscription for a device" + operationId: createSubscription + parameters: + - $ref: "#/components/parameters/x-correlator" + security: + - openId: + - connectivity-insights:subscriptions:write + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionRequest" + required: true + callbacks: + notifications: + "{$request.body#/sink}": + post: + summary: "Subscription notification callback" + description: | + Important: this endpoint is to be implemented by the API + consumer.The Connectivity Insights server will call this + endpoint whenever a connectivity event occurs that changes + the netowrk's ability to meet the application's demands for + a given device. + operationId: postNotification + parameters: + - $ref: "#/components/parameters/x-correlator" + requestBody: + required: true + content: + application/cloudevents+json:: + schema: + $ref: "#/components/schemas/CloudEvent" + + responses: + "204": + description: Successful notification + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "410": + $ref: "#/components/responses/Generic410" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + security: + - {} + - notificationsBearerAuth: [] + responses: + "201": + description: Created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + "202": + description: | + Request accepted to be processed. It applies for async + creation process. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionAsync" + "400": + $ref: "#/components/responses/CreateSubscriptionBadRequest400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/SubscriptionPermissionDenied403" + "409": + $ref: "#/components/responses/Generic409" + "415": + $ref: "#/components/responses/Generic415" + "422": + $ref: "#/components/responses/CreateSubscriptionUnprocessableEntity422" + "429": + $ref: "#/components/responses/Generic429" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + get: + tags: + - Connectivity Insights Subscriptions + summary: "Retrieve a list of apiName event subscription" + operationId: getSubscriptionList + description: | + Operation to list subscriptions authorized to be retrieved by the + provided access token. + parameters: + - $ref: "#/components/parameters/x-correlator" + security: + - openId: + - connectivity-insights:subscriptions:read + responses: + "200": + description: List of event subscription details + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + type: array + minItems: 0 + items: + $ref: "#/components/schemas/Subscription" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + /subscriptions/{subscriptionId}: + get: + tags: + - Connectivity Insights Subscriptions + summary: "Operation to retrieve a subscription based on the provided ID" + operationId: getSubscription + description: Retrieve a given subscription by ID + security: + - openId: + - connectivity-insights:subscriptions:read + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "200": + description: OK + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + "400": + $ref: "#/components/responses/SubscriptionIdRequired" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + + delete: + tags: + - Connectivity Insights Subscriptions + summary: "Operation to delete a subscription" + operationId: deleteSubscription + description: Delete a given subscription by ID + security: + - openId: + - connectivity-insights:subscriptions:write + parameters: + - $ref: "#/components/parameters/SubscriptionId" + - $ref: "#/components/parameters/x-correlator" + responses: + "204": + description: apiName subscription deleted + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + "202": + description: | + Request accepted to be processed. It applies for async deletion + process. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionAsync" + "400": + $ref: "#/components/responses/SubscriptionIdRequired" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + +components: + securitySchemes: + openId: + description: OpenID Provider Configuration Information + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + notificationsBearerAuth: + description: Bearer authorization for notifications + type: http + scheme: bearer + bearerFormat: "{$request.body#/sinkCredential.credentialType}" + parameters: + SubscriptionId: + name: subscriptionId + in: path + description: | + Subscription identifier that was obtained from the create event + subscription operation + required: true + schema: + $ref: "#/components/schemas/SubscriptionId" + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + + schemas: + AdditionalKpis: + description: additional information about connectivity quality + type: object + properties: + signalStrength: + description: | + rough indication of the end user device radio signal conditions + type: string + enum: + - excellent + - good + - fair + - poor + - no signal + connectivityType: + description: | + the access technology connecting the user device to the operator + network + type: string + enum: + - 5G-SA + - 5G-NSA + - 4G + - 3G + + Subscription: + description: Represents a event-type subscription. + type: object + required: + - sink + - protocol + - config + - types + - id + - startsAt + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: | + The address to which events shall be delivered using the selected + protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: + $ref: "#/components/schemas/SinkCredential" + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: for the Commonalities meta-release v0.4 we enforce to have + only event type per subscription then for following meta-release + use of array MUST be decided at API project level. + type: array + items: + type: string + config: + $ref: "#/components/schemas/Config" + subscriptionId: + type: string + description: | + The unique identifier of the subscription in the scope of the + subscription manager. When this information is contained within + an event notification, this concept SHALL be referred as + `subscriptionId` as per + [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). + example: "1119920371" + startsAt: + type: string + format: date-time + description: Date when the event subscription will begin/began + expiresAt: + type: string + format: date-time + description: | + Date when the event subscription will expire. Only provided when + `subscriptionExpireTime` is indicated by API client or Telco + Operator has specific policy about that. + status: + type: string + description: |- + Current status of the subscription - Management of Subscription + State engine is not mandatory for now. Note not all statuses may + be considered to be implemented. Details: + - `ACTIVATION_REQUESTED`: Subscription creation (POST) is + triggered but subscription creation process is not finished + yet. + - `ACTIVE`: Subscription creation process is completed. + Subscription is fully operative. + - `DEACTIVE`: Subscription is temporarily inactive, but its + workflow logic is not deleted. + - `EXPIRED`: Subscription is ended (no longer active). + This status applies when subscription is ended due to + `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event. + - `DELETED`: Subscription is ended as deleted (no longer + active). This status applies when subscription information is + kept (i.e. subscription workflow is no longer active but its + metainformation is kept). + enum: + - ACTIVATION_REQUESTED + - ACTIVE + - EXPIRED + - DEACTIVE + - DELETED + discriminator: + propertyName: protocol + mapping: + HTTP: "#/components/schemas/HTTPSubscriptionResponse" + MQTT3: "#/components/schemas/MQTTSubscriptionResponse" + MQTT5: "#/components/schemas/MQTTSubscriptionResponse" + AMQP: "#/components/schemas/AMQPSubscriptionResponse" + NATS: "#/components/schemas/NATSSubscriptionResponse" + KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse" + + SubscriptionAsync: + description: | + Response for a event-type subscription request managed asynchronously + (Creation or Deletion) + type: object + properties: + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + + SubscriptionId: + type: string + description: | + The unique identifier of the subscription in the scope of the + subscription manager. When this information is contained within + an event notification, this concept SHALL be referred as + `subscriptionId` as per + [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification). + example: qs15-h556-rt89-1298 + Device: + description: | + End-user equipment able to connect to a mobile network. Examples of + devices include smartphones or IoT sensors/actuators. + + The developer can choose to provide the below specified device + identifiers: + + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + + NOTE1: the MNO might support only a subset of these options. The + API invoker can provide multiple identifiers to be compatible across + different MNOs. In this case the identifiers MUST belong to the same + device. + NOTE2: for the Commonalities release v0.4, we are enforcing that the + networkAccessIdentifier is only part of the schema for future-proofing, + and CAMARA does not currently allow its use. After the CAMARA + meta-release work is concluded and the relevant issues are resolved, + its use will need to be explicitly documented in the guidelines. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 + + NetworkAccessIdentifier: + description: | + A public identifier addressing a subscription in a mobile network. In + 3GPP terminology, it corresponds to the GPSI formatted with the + External Identifier ({Local Identifier}@{Domain Identifier}). Unlike + the telephone number, the network access identifier is not subjected + to portability ruling in force, and is individually managed by each + operator. + type: string + 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 '+'. + type: string + pattern: '^\+?[0-9]{5,15}$' + example: "123456789" + + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP + address and port as seen by the application server, or the private + (local) and any public (observed) IP addresses in use by the device + (this information can be obtained by various means, for example from + some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is + not in use) then the same address should be specified for both + publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its + publicAddress and publicPort, or separately by its allocated IPv6 + address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one + of either privateAddress or publicPort, dependent upon which is known. + In general, mobile devices cannot be identified by their public IPv4 + address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: {"publicAddress":"84.125.93.10", "publicPort":59765} + + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" + + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any + single IPv6 address from within the subnet allocated to the device + (e.g. adding ::0 to the /64 prefix). + + The session shall apply to all IP flows between the device subnet and + the specified application server, unless further restricted by the + optional parameters devicePorts or applicationServerPorts. + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + + PortsSpec: + description: Specification of several TCP or UDP ports + type: object + minProperties: 1 + properties: + ranges: + description: Range of TCP or UDP ports + type: array + minItems: 1 + items: + type: object + required: + - from + - to + properties: + from: + $ref: "#/components/schemas/Port" + to: + $ref: "#/components/schemas/Port" + ports: + description: Array of TCP or UDP ports + type: array + minItems: 1 + items: + $ref: "#/components/schemas/Port" + example: + ranges: + - from: 5010 + to: 5020 + ports: + - 5060 + - 5070 + + Protocol: + type: string + enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"] + description: | + Identifier of a delivery protocol. Only HTTP is allowed for now + example: "HTTP" + + ApplicationServer: + description: | + A server hosting backend applications to deliver some business logic to + clients. + + The developer can choose to provide the below specified device + identifiers: + + * `ipv4Address` + * `ipv6Address` + + The Operator will use this information to calculate the end to end + network performance in scenarios where its feasible. + type: object + properties: + ipv4Address: + $ref: "#/components/schemas/ApplicationServerIpv4Address" + ipv6Address: + $ref: "#/components/schemas/ApplicationServerIpv6Address" + minProperties: 1 + ApplicationServerIpv4Address: + type: string + example: "192.168.0.1/24" + description: | + IPv4 address may be specified in form
as: + - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this + exact IP number will match the flow control rule. + - address/mask - an IP number as above with a mask width of the + form 1.2.3.4/24. + In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. + The bit width MUST be valid for the IP version. + + ApplicationServerIpv6Address: + type: string + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: | + IPv6 address may be specified in form
as: + - address - The /128 subnet is optional for single addresses: + - 2001:db8:85a3:8d3:1319:8a2e:370:7344 + - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 + - address/mask - an IP v6 number with a mask: + - 2001:db8:85a3:8d3::0/64 + - 2001:db8:85a3:8d3::/64 + Config: + description: | + Implementation-specific configuration parameters needed by the + subscription manager for acquiring events. + In CAMARA we have predefined attributes like `subscriptionExpireTime`, + `subscriptionMaxEvents`, `initialEvent` + Specific event type attributes must be defined in `subscriptionDetail` + Note: if a request is performed for several event type, all subscribed + event will use same `config` parameters. + type: object + required: + - subscriptionDetail + properties: + subscriptionDetail: + $ref: "#/components/schemas/CreateSubscriptionDetail" + subscriptionExpireTime: + type: string + format: date-time + example: 2023-01-17T13:18:23.682Z + description: | + The subscription expiration time (in date-time format) requested by + the API consumer. Up to API project decision to keep it. + subscriptionMaxEvents: + type: integer + description: | + Identifies the maximum number of event reports to be generated + (>=1) requested by the API consumer - Once this number is reached, + the subscription ends. Up to API project decision to keep it. + minimum: 1 + example: 5 + initialEvent: + type: boolean + description: | + Set to `true` by API consumer if consumer wants to get an event as + soon as the subscription is created and current situation reflects + event request. + Example: Consumer request Roaming event. If consumer sets + initialEvent to true and device is in roaming situation, an event + is triggered Up to API project decision to keep it. + SinkCredential: + type: object + description: | + A sink credential provides authentication or authorization information + properties: + credentialType: + type: string + enum: + - PLAIN + - ACCESSTOKEN + - REFRESHTOKEN + description: "The type of the credential." + discriminator: + propertyName: credentialType + mapping: + PLAIN: "#/components/schemas/PlainCredential" + ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" + REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential" + required: + - credentialType + + CreateSubscriptionDetail: + description: The detail of the requested event subscription + type: object + properties: + device: + $ref: "#/components/schemas/Device" + applicationServer: + $ref: "#/components/schemas/ApplicationServer" + applicationServerPorts: + description: | + A list of single ports or port ranges on the application server + allOf: + - $ref: "#/components/schemas/PortsSpec" + applicationProfileId: + $ref: "#/components/schemas/ApplicationProfileId" + required: + - device + - applicationProfileId + + SubscriptionRequest: + description: The request for creating a event-type event subscription + type: object + required: + - sink + - protocol + - config + - types + properties: + protocol: + $ref: "#/components/schemas/Protocol" + sink: + type: string + format: url + description: | + The address to which events shall be delivered using the selected + protocol. + example: "https://endpoint.example.com/sink" + sinkCredential: + $ref: "#/components/schemas/SinkCredential" + types: + description: | + Camara Event types eligible to be delivered by this subscription. + Note: for the Commonalities meta-release v0.4 we enforce to have + only event type per subscription then for following meta-release + use of array MUST be decided at API project level. + type: array + items: + type: string + example: camaraproject.connectivityinsights.v0. + networkQuality-event,org.camaraproject.connectivityinsights. + v0.eventSubscriptionEnd + config: + $ref: "#/components/schemas/Config" + + 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: + papplicationProfileId: + $ref: "#/components/schemas/ApplicationProfileId" + 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" + + PolicyFulfillmentConfidence: + type: string + description: | + a plain-language indicator of how confident the network is to meet a + given network demand. + enum: + - meets the application requirements + - unable to meet the application requirements + + ApplicationProfileId: + description: Identifier for the Application Profile + type: string + format: uuid + + Source: + type: string + format: uri-reference + minLength: 1 + description: | + Identifies the context in which an event happened, as a non-empty + `URI-reference` like: + - URI with a DNS authority: + * https://github.com/cloudevents + * mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique URN with a UUID: + * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Application-specific identifier: + * /cloudevents/spec/pull/123 + * 1-555-123-4567 + example: "https://notificationSendServer12.supertelco.com" + CloudEvent: + description: The Cloud-Event used for the callback. + required: + - id + - source + - specversion + - type + - time + properties: + id: + type: string + description: | + identifier of this event, that must be unique in the source context. + source: + $ref: "#/components/schemas/Source" + type: + $ref: "#/components/schemas/Event-typeNotification" + specversion: + type: string + description: | + Version of the specification to which this event conforms (must be + 1.0 if it conforms to cloudevents 1.0.2 version) + enum: + - "1.0" + datacontenttype: + type: string + description: | + 'media-type that describes the event payload encoding, + must be "application/json" for CAMARA APIs' + enum: + - application/json + data: + $ref: "#/components/schemas/NetworkQualityInsight" + time: + $ref: "#/components/schemas/DateTime" + discriminator: + propertyName: "type" + mapping: + org.camaraproject.connectivityinsights.v0.networkQuality-event: + "#/components/schemas/NetworkQualityTypeEvent" + org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: + "#/components/schemas/EventSubscriptionEnds" + + NetworkQualityTypeEvent: + description: event structure for event-type event + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/NetworkQualityInsight" + + EventSubscriptionEnds: + description: event structure for event subscription ends + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/SubscriptionEnds" + + SubscriptionEnds: + description: Event detail structure for SUBSCRIPTION_ENDS event + type: object + required: + - terminationReason + - subscriptionId + properties: + terminationReason: + $ref: "#/components/schemas/TerminationReason" + subscriptionId: + $ref: "#/components/schemas/SubscriptionId" + terminationDescription: + type: string + + TerminationReason: + type: string + description: | + - NETWORK_TERMINATED - API server stopped sending notification + - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by + the requester) has been reached + - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the + requester) has been reached + - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by + the requester) expiration time has been reached + enum: + - MAX_EVENTS_REACHED + - NETWORK_TERMINATED + - SUBSCRIPTION_EXPIRED + - ACCESS_TOKEN_EXPIRED + + DateTime: + type: string + format: date-time + description: | + Timestamp of when the occurrence happened. Must adhere to RFC 3339. + example: "2018-04-05T17:31:00Z" + + Event-typeNotification: + type: string + description: | + event-type - Event triggered when an event-type event occurred + subscription-ends: Event triggered when the subscription ends + enum: + - org.camaraproject.connectivityinsights.v0.networkQuality-met + - org.camaraproject.connectivityinsights.v0.networkQuality-not-met + - org.camaraproject.connectivityinsights.v0.subscription-ends + + ErrorInfo: + type: object + description: Error information + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP status code returned along with this error response + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + + responses: + CreateSubscriptionBadRequest400: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + GENERIC_400_INVALID_PROTOCOL: + value: + status: 400 + code: "INVALID_PROTOCOL" + message: "Only HTTP is supported" + GENERIC_400_INVALID_CREDENTIAL: + value: + status: 400 + code: "INVALID_CREDENTIAL" + message: "Only Access token is supported" + GENERIC_400_INVALID_TOKEN: + value: + status: 400 + code: "INVALID_TOKEN" + message: "Only bearer token is supported" + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + Generic401: + description: Authentication problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + Generic403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + SubscriptionPermissionDenied403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + GENERIC_403_SUBSCRIPTION_MISMATCH: + value: + status: 403 + code: "SUBSCRIPTION_MISMATCH" + message: "Inconsistent access token for requested events subscription" + Generic404: + description: Resource Not Found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + Generic409: + description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. + Generic415: + description: Unsupported Media Type + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format + CreateSubscriptionUnprocessableEntity422: + description: Unprocessable Entity + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: + value: + status: 422 + code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED" + message: "Multi event types subscription not managed" + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + Generic429: + description: Too Many Requests + headers: + X-Correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + Generic500: + description: Server error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic503: + description: Service unavailable. Typically the server is down. + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + SubscriptionIdRequired: + description: Problem with the client request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + Generic400: + summary: Schema validation failed + value: + status: 400 + code: INVALID_ARGUMENT + message: "Client specified an invalid argument, request body or query param" + subscriptionIdRequired: + summary: subscription id is required + value: + status: 400 + code: INVALID_ARGUMENT + message: "Expected property is missing: subscriptionId" diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index 330c2a2..825486d 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -150,6 +150,22 @@ paths: application/json: schema: $ref: "#/components/schemas/NetworkQualityInsightResponse" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + "422": + $ref: "#/components/responses/Generic422" + "500": + $ref: "#/components/responses/Generic500" + "503": + $ref: "#/components/responses/Generic503" + "504": + $ref: "#/components/responses/Generic504" components: securitySchemes: @@ -474,12 +490,6 @@ components: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. - GENERIC_400_OUT_OF_RANGE: - description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested - value: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range. Generic401: description: Unauthorized headers: @@ -496,21 +506,15 @@ components: status: 401 code: UNAUTHENTICATED message: Request not authenticated due to missing, invalid, or expired credentials. - GENERIC_401_AUTHENTICATION_REQUIRED: - description: New authentication is needed, authentication is no longer valid - value: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required. Generic403: description: Forbidden headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_403_PERMISSION_DENIED: description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security @@ -523,9 +527,9 @@ components: value: status: 403 code: INVALID_TOKEN_CONTEXT - message: "{{field}} is not consistent with access token." + message: phoneNumber is not consistent with access token Generic404: - description: Resource Not Found + description: Not found headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -540,88 +544,6 @@ components: status: 404 code: NOT_FOUND message: The specified resource is not found. - GENERIC_404_DEVICE_NOT_FOUND: - description: Device identifier not found - value: - status: 404 - code: DEVICE_NOT_FOUND - message: Device identifier not found. - Generic405: - description: Method Not Allowed - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_405_METHOD_NOT_ALLOWED: - description: Invalid HTTP verb used with a given endpoint - value: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target resource. - Generic409: - description: Conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_409_ABORTED: - description: Concurreny of processes of the same nature/scope - value: - status: 409 - code: ABORTED - message: Concurrency conflict. - GENERIC_409_ALREADY_EXISTS: - description: Trying to create an existing resource - value: - status: 409 - code: ALREADY_EXISTS - message: The resource that a client tried to create already exists. - GENERIC_409_CONFLICT: - description: Duplication of an existing resource - value: - status: 409 - code: CONFLICT - message: A specified resource duplicate entry found. - Generic410: - description: Gone - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_410_GONE: - description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available - value: - status: 410 - code: GONE - message: Access to the target resource is no longer available. - Generic415: - description: Unsupported Media Type - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_415_UNSUPPORTED_MEDIA_TYPE: - description: Payload format of the request is in an unsupported format by the Server. Should not happen - value: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: The server refuses to accept the request because the payload format is in an unsupported format. Generic422: description: Unprocessable Content headers: @@ -632,46 +554,18 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: - description: Inconsistency between device identifiers not pointing to the same device - value: - status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH - message: Provided device identifiers are not consistent. - GENERIC_422_DEVICE_NOT_APPLICABLE: - description: Service is not available for the provided device + GENERIC_422_NOT_SUPPORTED: + description: Not Supported value: status: 422 - code: DEVICE_NOT_APPLICABLE - message: The service is not available for the provided device. - GENERIC_422_UNIDENTIFIABLE_DEVICE: - description: The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token + code: NOT_SUPPORTED + message: Service not supported for this phoneNumber + UNIDENTIFIABLE_PHONE_NUMBER: + description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token value: status: 422 - code: UNIDENTIFIABLE_DEVICE - message: The device cannot be identified. - Generic429: - description: Too Many Requests - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_429_QUOTA_EXCEEDED: - description: Request is rejected due to exceeding a business quota limit - value: - status: 429 - code: QUOTA_EXCEEDED - message: Either out of resource quota or reaching rate limiting. - GENERIC_429_TOO_MANY_REQUESTS: - description: API Server request limit is overpassed - value: - status: 429 - code: TOO_MANY_REQUESTS - message: Either out of resource quota or reaching rate limiting. + code: UNIDENTIFIABLE_PHONE_NUMBER + message: The phone number cannot be identified Generic500: description: Internal Server Error headers: @@ -688,38 +582,6 @@ components: status: 500 code: INTERNAL message: Unknown server error. Typically a server bug. - Generic501: - description: Not Implemented - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_501_NOT_IMPLEMENTED: - description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations - value: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet. - Generic502: - description: Bad Gateway - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_502_BAD_GATEWAY: - description: Internal routing problem in the Server side that blocks to manage the service properly - value: - status: 502 - code: BAD_GATEWAY - message: An upstream internal service cannot be reached. Generic503: description: Service Unavailable headers: @@ -751,4 +613,4 @@ components: value: status: 504 code: TIMEOUT - message: Request timeout exceeded. + message: Request timeout exceeded. \ No newline at end of file From 66d63bdd5f4dfe38517af6dc893375b864cb2eaf Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 00:05:34 -0500 Subject: [PATCH 09/33] fixing linting error for no new line character at the end of file. --- code/API_definitions/connectivity-insights.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index 825486d..f0cb859 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -613,4 +613,4 @@ components: value: status: 504 code: TIMEOUT - message: Request timeout exceeded. \ No newline at end of file + message: Request timeout exceeded. From a02c36e36d3b1267a185eb61f0cb1a631e983266 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 00:49:31 -0500 Subject: [PATCH 10/33] addressing issues as per review comments in #PR 67 specific to application profiles yaml. --- .../API_definitions/application-profiles.yaml | 206 ++++++++++++------ 1 file changed, 141 insertions(+), 65 deletions(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index 6f3efa3..c590717 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -33,7 +33,7 @@ paths: post: security: - openId: - - connectivity_insights:policy:write + - application-profile:write tags: - Application Profiles summary: | @@ -45,47 +45,47 @@ paths: requestBody: description: List of user-defined network quality thresholds content: - "*/*": + application/json: schema: $ref: "#/components/schemas/NetworkQualityThresholds" required: true responses: - "200": - description: OK + "201": + description: Created + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: - $ref: "#/components/schemas/ApplicationProfileId" + $ref: "#/components/schemas/ApplicationProfile" "400": $ref: "#/components/responses/Generic400" "401": $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "409": - $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" "503": $ref: "#/components/responses/Generic503" /application-profiles/{applicationProfileId}: - put: + patch: security: - openId: - - connectivity_insights:application_profile:write + - application-profile:write tags: - Application Profiles description: | - Update the network quality thresholds for an application that ensure - good end user experience + Update the complete set of network quality thresholds for an + application with the new set of thresholds to ensure good + end user experience operationId: updateApplicationProfile parameters: - name: applicationProfileId in: path - description: Identifier for the Aplpication Profile + description: Identifier for the Application Profile required: true style: simple explode: false @@ -94,10 +94,10 @@ paths: format: uuid requestBody: description: | - Update the network quality thresholds that the application needs to - deliver an acceptable user experience. + network monitoring intents for optimal end user application + experience. content: - "*/*": + application/json: schema: $ref: "#/components/schemas/ApplicationProfile" required: true @@ -116,7 +116,7 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "409": + "405": $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" @@ -126,7 +126,7 @@ paths: get: security: - openId: - - connectivity_insights:application_profile:read + - application-profile:read tags: - Application Profiles description: Read an Application Profile @@ -166,7 +166,7 @@ paths: delete: security: - openId: - - connectivity_insights:application_profile:write + - application-profile:delete tags: - Application Profiles description: delete @@ -202,9 +202,14 @@ paths: components: securitySchemes: openId: + description: OpenID Provider Configuration Information type: openIdConnect - openIdConnectUrl: .well-known/openid-configuration - + openIdConnectUrl: https://example.com/.well-known/openid-configuration + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string schemas: Duration: type: object @@ -312,6 +317,9 @@ components: ApplicationProfile: type: object + required: + - applicationProfileId + - networkQualityThresholds properties: applicationProfileId: type: string @@ -333,10 +341,6 @@ components: jitter: $ref: "#/components/schemas/jitter" - ApplicationProfileId: - type: string - format: uuid - ErrorInfo: type: object description: Error information @@ -357,78 +361,150 @@ components: responses: Generic400: - description: Invalid argument + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 400 - code: INVALID_ARGUMENT - message: "Invalid argument" - + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: - description: Unauthenticated + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 401 - code: UNAUTHENTICATED - message: "Authorization failed: ..." - + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. Generic403: - description: Permission denied + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 403 - code: PERMISSION_DENIED - message: "Operation not allowed: ..." - + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." Generic404: description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 404 - code: NOT_FOUND - message: "The specified resource is not found" - + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. Generic409: description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 409 - code: Conflict - message: "There is conflict in the request" - + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. Generic500: - description: Internal server error + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 500 - code: INTERNAL - message: "Internal server error" - + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. Generic503: - description: Service unavailable + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" - example: - status: 503 - code: UNAVAILABLE - message: "Service unavailable" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. From 542013ceda36ee11b963b5fb7ccac63b3c874a3f Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 00:54:22 -0500 Subject: [PATCH 11/33] updates error response codes as per review comments. --- code/API_definitions/application-profiles.yaml | 4 ---- code/Test_definitions/application-profiles.feature | 4 ++-- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index c590717..802e610 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -156,8 +156,6 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "409": - $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" "503": @@ -192,8 +190,6 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "409": - $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" "503": diff --git a/code/Test_definitions/application-profiles.feature b/code/Test_definitions/application-profiles.feature index 4b9e019..effadc5 100644 --- a/code/Test_definitions/application-profiles.feature +++ b/code/Test_definitions/application-profiles.feature @@ -12,7 +12,7 @@ Feature: Application Profiles API automated test 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 + Then Response code is 201 Created And The response body complies with ApplicationProfileId object @applicationProfile_retrieveById_1_success @@ -24,7 +24,7 @@ Feature: Application Profiles API automated test @applicationProfile_updateApplicationProfileById_1_success Scenario: Update details based on specific ApplicationProfileId - Given the API Client makes a PUT request to the {path_resource} + Given the API Client makes a PATCH 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 From 4264c23102d2c04c80ae3f06c3bec76f9ab047fc Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 00:56:27 -0500 Subject: [PATCH 12/33] updated test cases as per the updates yaml files. --- ...onnectivity-insights-subscriptions.feature | 37 +++++++++++++++++++ .../connectivity-insights.feature | 28 -------------- 2 files changed, 37 insertions(+), 28 deletions(-) create mode 100644 code/Test_definitions/connectivity-insights-subscriptions.feature diff --git a/code/Test_definitions/connectivity-insights-subscriptions.feature b/code/Test_definitions/connectivity-insights-subscriptions.feature new file mode 100644 index 0000000..96025ed --- /dev/null +++ b/code/Test_definitions/connectivity-insights-subscriptions.feature @@ -0,0 +1,37 @@ + +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_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/code/Test_definitions/connectivity-insights.feature b/code/Test_definitions/connectivity-insights.feature index 5190501..7a63d17 100644 --- a/code/Test_definitions/connectivity-insights.feature +++ b/code/Test_definitions/connectivity-insights.feature @@ -14,31 +14,3 @@ Feature: Connectivity Insights API automated test 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 From 03ea4c3a667f106bf98c77c97d8b1c090b6b1149 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 01:11:51 -0500 Subject: [PATCH 13/33] created change log and api readiness checklist as per review comments --- CHANGELOG.md | 45 ++++++++++++++----- ...s-Subscriptions-API-Readiness-Checklist.md | 27 +++++++++++ 2 files changed, 61 insertions(+), 11 deletions(-) create mode 100644 documentation/API_documentation/Connectivity-Insights-Subscriptions-API-Readiness-Checklist.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 72d3bf9..fb12c69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,8 +18,9 @@ The below sections record the changes for each API version in each (pre-)release ## Release Notes This release contains the definition and documentation of -* Connectivity Insights API -* Application Profiles API +* Connectivity Insights API v0.4.0 +* Connectivity Insights Subscriptions API v0.4.0 +* Application Profiles API v0.3.0 The API definition(s) are based on * Commonalities v0.4.0-rc.1 @@ -28,15 +29,13 @@ The API definition(s) are based on ## 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. +- This is the first release of the API. - 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) - + - 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) @@ -56,17 +55,42 @@ The API definition(s) are based on - Error model alignment, including device identifier-related errors - Updated the API Readiness Checklist to the new format -## Application Profiles API 0.3.0-rc.1 +## Connectivity Insights Subscriptions API v0.4.0-rc.1 +** 0.4.0-rc.1 is the first release-candidate version for connectivity insights subscriptions API** +- 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. +- This is the first release of the API. +- API definition **with inline documentation**: + - View it on ReDoc: + - [connectivity-insights-subscriptions.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights-subscriptions.yaml&nocors) -** 0.3.0-rc.1 is the first release-candidate version for application profile.** + - View it on Swagger Editor + - [connectivity-insights-subscriptions.yaml](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights-subscriptions.yaml) + - OpenAPI + - [connectivity-insights-subscriptions.yaml](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/r1.1/code/API_definitions/connectivity-insights-subscriptions.yaml) -### Main changes +### 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 + +## Application Profiles API 0.3.0-rc.1 + + + +** 0.3.0-rc.1 is the first release-candidate version for application profile.** - 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. +- This is the first release of the API. - API definition **with inline documentation**: - View it on ReDoc: @@ -80,7 +104,7 @@ The API definition(s) are based on ### Added -- Gherkin +- Gherkin `.feature` file in Test_definitions ### Changed @@ -88,4 +112,3 @@ The API definition(s) are based on - Aligned the network monitoring KPIs to match with Quality on Demand CAMARA API. - update the end points to make it more developer friendly based on the discussion in the API working group. - Updated the API Readiness Checklist to the new format - diff --git a/documentation/API_documentation/Connectivity-Insights-Subscriptions-API-Readiness-Checklist.md b/documentation/API_documentation/Connectivity-Insights-Subscriptions-API-Readiness-Checklist.md new file mode 100644 index 0000000..afeefda --- /dev/null +++ b/documentation/API_documentation/Connectivity-Insights-Subscriptions-API-Readiness-Checklist.md @@ -0,0 +1,27 @@ +# Connectivity Insights Subscriptions API Readiness minimum criteria checklist + +Checklist for connectivity-insights-subscriptions v0.4.0-rc.1 + +| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | +|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|----| +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/connectivity-insights-subscriptions.yaml) | +| 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 | Y | [link](/documentation/API_documentation/ConnectivityInsights-User-Story.md) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/connectivity-insights-subscriptions.feature) | +| 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 | 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. +- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, a "N" (no) or a "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release. +- in the Comments column, provide the link to the asset once available, and any other relevant comments. + +Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. + +The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/x/AgAVAQ) From f064bfe35dc4217dd35aee286ae84daa6c77ece0 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 01:36:54 -0500 Subject: [PATCH 14/33] updated descption for application profile yaml and also fixed url in connecitvity insights in the Authorization section. --- .../API_definitions/application-profiles.yaml | 26 +++++++++++++++++++ .../connectivity-insights.yaml | 9 +++---- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index 802e610..756ff8a 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -11,6 +11,32 @@ info: Application profiles allows application developers to share all the information about their application which would be relevant for network/ CAMARA APIs related decision making. + + To start with the API will provide operations to define, read and manage + an application's thresholds for network quality (latency, jitter, loss, + throughput). This scope will be expanded further based on addtional + requirements from other applicable CAMARA APIs + + # Authorization and Authentication + + [Camara Security and Interoperability Profile](https://github.com/ + camaraproject/IdentityAndConsentManagement/blob/r0.2.0-rc.2/ + 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. x-camara-commonalities: 0.4.0 servers: diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index f0cb859..12300b6 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -72,11 +72,10 @@ info: # Authorization and Authentication - The "Camara Security and Interoperability Profile" provides details on - how a client requests an access token. Please refer to - Identify and Consent Management - (https://github.com/camaraproject/IdentityAndConsentManagement/) for the - released version of the Profile. + [Camara Security and Interoperability Profile](https://github.com/ + camaraproject/IdentityAndConsentManagement/blob/r0.2.0-rc.2/ + 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 From 8f08f70b19dc8564b7acdde47768363e1c3dfe12 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Fri, 16 Aug 2024 08:46:51 -0500 Subject: [PATCH 15/33] removed the invalid 405 response code which was incorrectly pointing to 409 definition path. --- .../API_definitions/application-profiles.yaml | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index 756ff8a..e2f0b5b 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -142,8 +142,6 @@ paths: $ref: "#/components/responses/Generic403" "404": $ref: "#/components/responses/Generic404" - "405": - $ref: "#/components/responses/Generic409" "500": $ref: "#/components/responses/Generic500" "503": @@ -470,34 +468,6 @@ components: status: 404 code: DEVICE_NOT_FOUND message: Device identifier not found. - Generic409: - description: Conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_409_ABORTED: - description: Concurreny of processes of the same nature/scope - value: - status: 409 - code: ABORTED - message: Concurrency conflict. - GENERIC_409_ALREADY_EXISTS: - description: Trying to create an existing resource - value: - status: 409 - code: ALREADY_EXISTS - message: The resource that a client tried to create already exists. - GENERIC_409_CONFLICT: - description: Duplication of an existing resource - value: - status: 409 - code: CONFLICT - message: A specified resource duplicate entry found. Generic500: description: Internal Server Error headers: From 7acdc0b9cf5cfef21af872a00028198c778d3f92 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Mon, 19 Aug 2024 14:58:06 -0500 Subject: [PATCH 16/33] fix for issue #79 --- code/API_definitions/application-profiles.yaml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index e2f0b5b..83ffe52 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -73,7 +73,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/NetworkQualityThresholds" + $ref: "#/components/schemas/ApplicationProfileRequest" required: true responses: "201": @@ -205,7 +205,7 @@ paths: format: uuid responses: "200": - description: policy has been deleted + description: application profile has been deleted "400": $ref: "#/components/responses/Generic400" "401": @@ -347,6 +347,14 @@ components: networkQualityThresholds: $ref: "#/components/schemas/NetworkQualityThresholds" + ApplicationProfileRequest: + type: object + required: + - networkQualityThresholds + properties: + networkQualityThresholds: + $ref: "#/components/schemas/NetworkQualityThresholds" + NetworkQualityThresholds: type: object properties: From ed8c9b4358963d0ba894c95b4c6ec42a9738bd26 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Mon, 19 Aug 2024 15:04:34 -0500 Subject: [PATCH 17/33] createProfile -> createApplicationProfile for consistent naming --- code/API_definitions/application-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index 83ffe52..d44ae84 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -67,7 +67,7 @@ paths: description: | Define network monitoring intents for optimal end user application experience. - operationId: createProfile + operationId: createApplicationProfile requestBody: description: List of user-defined network quality thresholds content: From d6917f2729d0ec977c430945f291a8e179dadd9d Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:35:33 -0500 Subject: [PATCH 18/33] Update code/API_definitions/connectivity-insights.yaml Co-authored-by: Herbert Damker --- code/API_definitions/connectivity-insights.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index 12300b6..b0aaefc 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -203,7 +203,7 @@ components: provided for predictive data. If no value is provided then the current date and time is used and network data for the monitoring data aggregation is used to check network performance against the - policy defined. + application profile defined. NetworkQualityInsightResponse: type: object From b01f1093c077fd86c25aed5fae80e45a7e621223 Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Tue, 20 Aug 2024 11:49:27 -0500 Subject: [PATCH 19/33] fix for issue #90 to update change log as per review comments. --- CHANGELOG.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb12c69..1ff61be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,9 +10,12 @@ NOTE: 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 +* 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 # r1.1 - rc ## Release Notes @@ -28,9 +31,8 @@ The API definition(s) are based on ## Connectivity Insights API v0.4.0-rc.1 -** 0.4.0-rc.1 is the first release-candidate version for connectivity insights** -- 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. -- This is the first release of the API. +0.4.0-rc.1 is the first release of the API. The version is aligned with +Commonalities 0.4.0-rc.2 and Identity and Consent Management v0.2.0-rc.2. - API definition **with inline documentation**: - View it on ReDoc: @@ -57,9 +59,8 @@ The API definition(s) are based on ## Connectivity Insights Subscriptions API v0.4.0-rc.1 -** 0.4.0-rc.1 is the first release-candidate version for connectivity insights subscriptions API** -- 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. -- This is the first release of the API. +0.4.0-rc.1 is the first release of the API. The version is aligned with +Commonalities 0.4.0-rc.2 and Identity and Consent Management v0.2.0-rc.2. - API definition **with inline documentation**: - View it on ReDoc: @@ -88,9 +89,8 @@ The API definition(s) are based on -** 0.3.0-rc.1 is the first release-candidate version for application profile.** -- 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. -- This is the first release of the API. +0.3.0-rc.1 is the first release of the API. The version is aligned with +Commonalities 0.4.0-rc.2 and Identity and Consent Management v0.2.0-rc.2. - API definition **with inline documentation**: - View it on ReDoc: From 658678bde33b90c5740b83b5caa367df28ebfb16 Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 09:45:15 -0500 Subject: [PATCH 20/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index a496620..0cdb1a5 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -111,7 +111,7 @@ paths: - $ref: "#/components/parameters/x-correlator" security: - openId: - - connectivity-insights:subscriptions:write + - connectivity-insights-subscriptions:create requestBody: content: application/json: From 1f4035032b8e54a7fba8d2b0c5698386c3356de7 Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 09:46:34 -0500 Subject: [PATCH 21/33] Update code/API_definitions/application-profiles.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/application-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index d44ae84..f58d45a 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -59,7 +59,7 @@ paths: post: security: - openId: - - application-profile:write + - application-profiles:create tags: - Application Profiles summary: | From 2259ae9ea9d1d34d2164ae54f2471778bd001b76 Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 09:46:44 -0500 Subject: [PATCH 22/33] Update code/API_definitions/application-profiles.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/application-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index f58d45a..9c00729 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -150,7 +150,7 @@ paths: get: security: - openId: - - application-profile:read + - application-profiles:read tags: - Application Profiles description: Read an Application Profile From 269665183928a550662c534f61b1cc2fdf55e02d Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 09:47:01 -0500 Subject: [PATCH 23/33] Update code/API_definitions/application-profiles.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/application-profiles.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index 9c00729..ea583f0 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -100,7 +100,7 @@ paths: patch: security: - openId: - - application-profile:write + - application-profiles:update tags: - Application Profiles description: | From a8839f81ecfe1751d8a128f8bb7ec6f715d6dcce Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:52:23 -0500 Subject: [PATCH 24/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../connectivity-insights-subscriptions.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 0cdb1a5..0039766 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -949,10 +949,9 @@ components: event-type - Event triggered when an event-type event occurred subscription-ends: Event triggered when the subscription ends enum: - - org.camaraproject.connectivityinsights.v0.networkQuality-met - - org.camaraproject.connectivityinsights.v0.networkQuality-not-met - - org.camaraproject.connectivityinsights.v0.subscription-ends - + - org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-met + - org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-not-met + - org.camaraproject.connectivity-insights-subscriptions.v0.subscription-ends ErrorInfo: type: object description: Error information From 598ffd44b632421d504babeffbc276209f0f4d64 Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:52:43 -0500 Subject: [PATCH 25/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 0039766..9e239e6 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -214,7 +214,7 @@ paths: - $ref: "#/components/parameters/x-correlator" security: - openId: - - connectivity-insights:subscriptions:read + - connectivity-insights-subscriptions:read responses: "200": description: List of event subscription details From 3112c90ee291e9cee1fbc8e1b641fd375d95523b Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:53:06 -0500 Subject: [PATCH 26/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 9e239e6..6f413f5 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -248,7 +248,7 @@ paths: description: Retrieve a given subscription by ID security: - openId: - - connectivity-insights:subscriptions:read + - connectivity-insights-subscriptions:read parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" From 949ecc675e522f8d147b2f99dde353266298250e Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:54:08 -0500 Subject: [PATCH 27/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 6f413f5..b0dc53f 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -943,7 +943,7 @@ components: Timestamp of when the occurrence happened. Must adhere to RFC 3339. example: "2018-04-05T17:31:00Z" - Event-typeNotification: + EventTypeNotification: type: string description: | event-type - Event triggered when an event-type event occurred From 837d17471775658bcf896f8ee085f622d1a2cf36 Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:54:22 -0500 Subject: [PATCH 28/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index b0dc53f..ed2e620 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -283,7 +283,7 @@ paths: description: Delete a given subscription by ID security: - openId: - - connectivity-insights:subscriptions:write + - connectivity-insights-subscriptions:delete parameters: - $ref: "#/components/parameters/SubscriptionId" - $ref: "#/components/parameters/x-correlator" From fb1211b4b57206d54bdddcb6ba6a5950e2c6415b Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:55:22 -0500 Subject: [PATCH 29/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../connectivity-insights-subscriptions.yaml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index ed2e620..cdff921 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -888,14 +888,24 @@ components: org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" - NetworkQualityTypeEvent: - description: event structure for event-type event + EventNetworkQualityMet: + description: event structure for Network Quality met allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: $ref: "#/components/schemas/NetworkQualityInsight" + + EventNetworkQualityNotMet: + description: event structure for Network Quality not met + allOf: + - $ref: "#/components/schemas/CloudEvent" + - type: object + properties: + data: + $ref: "#/components/schemas/NetworkQualityInsight" + EventSubscriptionEnds: description: event structure for event subscription ends From f4f8fb65ade2dc240081614178f85d2c7f4b80cc Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 14:56:08 -0500 Subject: [PATCH 30/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index cdff921..722eb63 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -111,7 +111,9 @@ paths: - $ref: "#/components/parameters/x-correlator" security: - openId: - - connectivity-insights-subscriptions:create + - connectivity-insights-subscriptions:org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-met:create + - connectivity-insights-subscriptions:org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-not-met:create + requestBody: content: application/json: From 87924221a7082902580d0af5b6b1b03588c20b4c Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 15:03:02 -0500 Subject: [PATCH 31/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- code/API_definitions/connectivity-insights-subscriptions.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 722eb63..9bfc09b 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -790,9 +790,7 @@ components: type: array items: type: string - example: camaraproject.connectivityinsights.v0. - networkQuality-event,org.camaraproject.connectivityinsights. - v0.eventSubscriptionEnd + example: org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-met config: $ref: "#/components/schemas/Config" From 0e6c9e7b7ab796496ebec6ceb473e4c39ca46c4a Mon Sep 17 00:00:00 2001 From: Mahesh <98130650+maheshc01@users.noreply.github.com> Date: Wed, 21 Aug 2024 15:03:23 -0500 Subject: [PATCH 32/33] Update code/API_definitions/connectivity-insights-subscriptions.yaml Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com> --- .../connectivity-insights-subscriptions.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 9bfc09b..0dca40f 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -883,8 +883,10 @@ components: discriminator: propertyName: "type" mapping: - org.camaraproject.connectivityinsights.v0.networkQuality-event: - "#/components/schemas/NetworkQualityTypeEvent" + org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-met: + "#/components/schemas/EventNetworkQualityMet" + org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-not-met: + "#/components/schemas/EventNetworkQualityNotMet" org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" From 630372b35ec23abd958e129a5c45e49e1876354a Mon Sep 17 00:00:00 2001 From: "Chapalamadugu, Mahesh" Date: Wed, 21 Aug 2024 15:30:16 -0500 Subject: [PATCH 33/33] fix for issue #91 and #94 --- CHANGELOG.md | 4 +- .../API_definitions/application-profiles.yaml | 22 +++-------- .../connectivity-insights-subscriptions.yaml | 37 +++++++------------ .../connectivity-insights.yaml | 26 ++++--------- ...cation-profiles-API-Readiness-Checklist.md | 2 +- 5 files changed, 29 insertions(+), 62 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ff61be..c667a3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,8 +26,8 @@ This release contains the definition and documentation of * Application Profiles API v0.3.0 The API definition(s) are based on -* Commonalities v0.4.0-rc.1 -* Identity and Consent Management v0.2.0-rc.1 +* Commonalities v0.4.0-rc.2 +* Identity and Consent Management v0.2.0-rc.2 ## Connectivity Insights API v0.4.0-rc.1 diff --git a/code/API_definitions/application-profiles.yaml b/code/API_definitions/application-profiles.yaml index ea583f0..8752d61 100644 --- a/code/API_definitions/application-profiles.yaml +++ b/code/API_definitions/application-profiles.yaml @@ -17,26 +17,14 @@ info: throughput). This scope will be expanded further based on addtional requirements from other applicable CAMARA APIs - # Authorization and Authentication + ### Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/ - camaraproject/IdentityAndConsentManagement/blob/r0.2.0-rc.2/ - documentation/CAMARA-Security-Interoperability.md) provides details on - how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. - 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. + 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. - 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. x-camara-commonalities: 0.4.0 servers: diff --git a/code/API_definitions/connectivity-insights-subscriptions.yaml b/code/API_definitions/connectivity-insights-subscriptions.yaml index 0dca40f..fe8678d 100644 --- a/code/API_definitions/connectivity-insights-subscriptions.yaml +++ b/code/API_definitions/connectivity-insights-subscriptions.yaml @@ -2,6 +2,8 @@ openapi: 3.0.3 info: title: Connectivity Insights version: 0.4.0-rc.1 + contact: + email: sp-coi@lists.camaraproject.org x-camara-commonalities: 0.4.0 description: | With CAMARA Connectivity Insights, application developers gain essential @@ -55,26 +57,13 @@ info: connectivity insights resource server to the webhook url provided by notification listener. - # Authorization and Authentication + ### Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/ - camaraproject/IdentityAndConsentManagement/blob/r0.2.0-rc.2/ - documentation/CAMARA-Security-Interoperability.md) provides details on - how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. - 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. + 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. + 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 @@ -861,7 +850,7 @@ components: source: $ref: "#/components/schemas/Source" type: - $ref: "#/components/schemas/Event-typeNotification" + $ref: "#/components/schemas/EventTypeNotification" specversion: type: string description: | @@ -885,12 +874,12 @@ components: mapping: org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-met: "#/components/schemas/EventNetworkQualityMet" - org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-not-met: + org.camaraproject.connectivity-insights-subscriptions.v0.network-quality-not-met: "#/components/schemas/EventNetworkQualityNotMet" org.camaraproject.connectivityinsights.v0.eventSubscriptionEnds: "#/components/schemas/EventSubscriptionEnds" - EventNetworkQualityMet: + EventNetworkQualityMet: description: event structure for Network Quality met allOf: - $ref: "#/components/schemas/CloudEvent" @@ -898,16 +887,16 @@ components: properties: data: $ref: "#/components/schemas/NetworkQualityInsight" - - EventNetworkQualityNotMet: + + EventNetworkQualityNotMet: description: event structure for Network Quality not met allOf: - $ref: "#/components/schemas/CloudEvent" - type: object properties: data: - $ref: "#/components/schemas/NetworkQualityInsight" - + $ref: "#/components/schemas/NetworkQualityInsight" + EventSubscriptionEnds: description: event structure for event subscription ends diff --git a/code/API_definitions/connectivity-insights.yaml b/code/API_definitions/connectivity-insights.yaml index b0aaefc..0fd7bce 100644 --- a/code/API_definitions/connectivity-insights.yaml +++ b/code/API_definitions/connectivity-insights.yaml @@ -2,6 +2,8 @@ openapi: 3.0.3 info: title: Connectivity Insights version: 0.4.0-rc.1 + contact: + email: sp-coi@lists.camaraproject.org x-camara-commonalities: 0.4.0 description: | With CAMARA Connectivity Insights, application developers gain essential @@ -38,7 +40,8 @@ info: 3. Optional: use the `connectivity-insights-subscriptions` API to receive notifications of network quality. - todo: sequence diagram + Following diagram shows the interaction between different components + ![Sequence Diagram](https://raw.githubusercontent.com/camaraproject/ConnectivityInsights/main/documentation/API_documentation/ConnectivityInsights-SequenceDiagram.png) # Identifying the device @@ -70,26 +73,13 @@ info: be explicitly documented in the guidelines. - # Authorization and Authentication + ### Authorization and authentication - [Camara Security and Interoperability Profile](https://github.com/ - camaraproject/IdentityAndConsentManagement/blob/r0.2.0-rc.2/ - documentation/CAMARA-Security-Interoperability.md) provides details on - how a client requests an access token. + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. - 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. + 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. + 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 diff --git a/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md b/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md index 077d176..f184994 100644 --- a/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md +++ b/documentation/API_documentation/application-profiles-API-Readiness-Checklist.md @@ -1,6 +1,6 @@ # API Readiness Checklist -Checklist for application-profile v0.3.0-rc.1 +Checklist for application-profiles v0.3.0-rc.1 | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Comments | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|----|