diff --git a/CHANGELOG/CHANGELOG-r1.md b/CHANGELOG/CHANGELOG-r1.md index be92354..4226dae 100644 --- a/CHANGELOG/CHANGELOG-r1.md +++ b/CHANGELOG/CHANGELOG-r1.md @@ -2,6 +2,7 @@ ## Table of Contents +- [r1.2](#r12) - [r1.1](#r11) @@ -14,6 +15,115 @@ The below sections record the changes for each API version in each release as fo * for subsequent release-candidate(s), only the delta to the previous release-candidate * for a public release, the consolidated changes since the previous public release +# r1.2 + +## Release Notes + +This release candidate contains the definition and documentation of +* edge-application-management 0.1.0-rc.1 + +The API definition(s) are based on +* Commonalities 0.8.0 +* Identity and Consent Management 0.5.0 + + +> **Working area — candidate changes (auto-removed on merge)** +> Copy relevant entries into the Breaking changes/Added/Changed/Fixed/Removed sections below. List breaking changes both in Breaking changes and in their normal change category. +> You may edit this list while triaging; it will be removed on merge. +> This working-area section is removed automatically when the PR is merged. + +
+Candidate changes (auto-generated from merged PRs) + +## What's Changed +* Update API scope and start date in README.md by @Kevsy in https://github.com/camaraproject/EdgeApplicationManagement/pull/3 +* Update MAINTAINERS.MD by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/5 +* Update CODEOWNERS by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/4 +* fix: corrected orgs in MAINTAINERS by @Kevsy in https://github.com/camaraproject/EdgeApplicationManagement/pull/8 +* Add User Story file by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/13 +* Delete documentation/API_documentation/README.MD by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/14 +* Add test files by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/12 +* Adding the definition of the API (YAML) by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/11 +* refactor: Align API definition with commonalities by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/16 +* fix(openapi): schema consistency fixes and comm aligment by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/18 +* Update release-plan.yaml by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/17 +* [bulk] Enable release automation and validation by @camara-release-automation[bot] in https://github.com/camaraproject/EdgeApplicationManagement/pull/20 +* Update release-plan.yaml by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/22 +* Sync common files from Commonalities r4.2 by @camara-release-automation[bot] in https://github.com/camaraproject/EdgeApplicationManagement/pull/24 +* Update MAINTAINERS.MD by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/19 +* [bulk] Update release-automation + validation callers by @camara-release-automation[bot] in https://github.com/camaraproject/EdgeApplicationManagement/pull/26 +* Update release-plan.yaml by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/29 +* fix: minor corrections from automatic validation by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/27 +* fix: add reference to CAMARA_common.yaml schemas by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/28 +* Sync common files from Commonalities r4.3 by @camara-release-automation[bot] in https://github.com/camaraproject/EdgeApplicationManagement/pull/30 +* Fix: Update testing files names by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/31 +* fix: reference to xcorrelator schema by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/33 +* Release Automation: Post-release sync (r1.1) by @camara-release-automation[bot] in https://github.com/camaraproject/EdgeApplicationManagement/pull/36 +* fix: mandatory templates for info.description by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/38 +* Update release-plan.yaml by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/37 +* Update release-plan.yaml by @JoseMConde in https://github.com/camaraproject/EdgeApplicationManagement/pull/41 +* Improve API definitions with common response components and validation patterns by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/44 +* Mark credential fields as writeOnly in EAM schema by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/55 +* Remove "API" from info.title per Design Guide 5.3.1 (#51) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/60 +* Fix broken regex, callback body shape, and externalDocs link (#50) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/59 +* Fix HTTP status codes to match Design Guide semantics (#48) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/56 +* Fix resource modelling inconsistencies across apps/instances/deployments (#49) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/58 +* Fix wrong operationId sent in several .feature files (#52) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/61 +* Fix phantom schemas, wrong error codes, and copy-paste bugs in feature files (#53) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/62 +* Add missing 401 scenarios and updateAppDeployment's 409 scenario (#54) by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/63 +* Fix CAMARA validation warnings from Actions run 30633755325 by @DLondonoD in https://github.com/camaraproject/EdgeApplicationManagement/pull/66 + +## New Contributors +* @Kevsy made their first contribution in https://github.com/camaraproject/EdgeApplicationManagement/pull/3 +* @JoseMConde made their first contribution in https://github.com/camaraproject/EdgeApplicationManagement/pull/5 + +
+ + +## edge-application-management 0.1.0-rc.1 + +**edge-application-management 0.1.0-rc.1 is the first release-candidate version of this API.** + +- API definition **with inline documentation**: + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.2/code/API_definitions/edge-application-management.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.2/code/API_definitions/edge-application-management.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/EdgeApplicationManagement/blob/r1.2/code/API_definitions/edge-application-management.yaml) + +### Breaking changes + +* `deleteApp` `409` error code changed from `ABORTED` to `INCOMPATIBLE_STATE` (#56) +* Removed `410 GONE` response from `getAppDeployments`, `deleteAppDeployment` and `updateAppDeployment` (#56) +* Removed `501 NOT_IMPLEMENTED` response from `submitApp`, `createAppInstance` and `createAppDeployment` (#56) +* `getAppInstance` (`GET /app-instances/{appInstanceId}`) is now a by-id-only operation; the list/filter behavior moved to the new `getAppInstances` (`GET /app-instances`) operation (#58) +* Removed the `appDeploymentId` query parameter filter from `getAppDeployments` (`GET /deployments`); retrieving a single deployment by id is now done via the new `getAppDeployment` (`GET /deployments/{appDeploymentId}`) operation (#58) +* `AccessTokenCredential.accessToken`, `AccessTokenCredential.accessTokenType` and `AppManifest.appRepo.credentials` are now marked `writeOnly` and will no longer be present in API responses (#55, #66) + +### Added + +* `getAppInstances` operation (`GET /app-instances`) to list application instances, with optional filtering by `appId` and `region` (#58) +* `getAppDeployment` operation (`GET /deployments/{appDeploymentId}`) to retrieve a single application deployment by id (#58) +* Missing `401 UNAUTHENTICATED` test scenarios across all operation `.feature` files, and the missing `409 ABORTED` test scenario for `updateAppDeployment` (#63) + +### Changed + +* Removed "API" from `info.title` per CAMARA API Design Guide rule 5.3.1 (#60) +* Documented the `x-correlator` response header on the `409` and `204` responses that were missing it (#66) + +### Fixed + +* Fixed broken regex pattern, incorrect callback request body shape, and a broken `externalDocs` link (#59) +* Marked credential fields `writeOnly` and restored `accessToken.maxLength` to `4096` to prevent credential exposure in API responses (#55, #66) +* Fixed wrong `operationId` values referenced in several `.feature` test definition files (#61) +* Fixed phantom schema references, wrong error codes, and copy-paste bugs across `.feature` test definition files (#62) + +### Removed + +* Removed `410 GONE` response from `getAppDeployments`, `deleteAppDeployment` and `updateAppDeployment` (#56) +* Removed `501 NOT_IMPLEMENTED` response from `submitApp`, `createAppInstance` and `createAppDeployment` (#56) +* Removed the `appDeploymentId` query parameter filter from `getAppDeployments`, superseded by the new by-id `getAppDeployment` operation (#58) + +**Full Changelog**: https://github.com/camaraproject/EdgeApplicationManagement/commits/r1.2 + # r1.1 ## Release Notes diff --git a/README.md b/README.md index f843c28..bfa0f66 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,9 @@ Sandbox API Repository to describe, develop, document, and test the EdgeApplicat > [!NOTE] > This repository has only pre-release versions available yet. Pre-releases are for testing and may change before public release. -* The latest pre-release is [r1.1](https://github.com/camaraproject/EdgeApplicationManagement/releases/tag/r1.1) (alpha), with the following API versions: - * **edge-application-management 0.1.0-alpha.1** - [[YAML]](https://github.com/camaraproject/EdgeApplicationManagement/blob/r1.1/code/API_definitions/edge-application-management.yaml) [[ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.1/code/API_definitions/edge-application-management.yaml&nocors) [[Swagger]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.1/code/API_definitions/edge-application-management.yaml) +* The latest pre-release is [r1.2](https://github.com/camaraproject/EdgeApplicationManagement/releases/tag/r1.2) (release candidate), with the following API versions: + * **edge-application-management 0.1.0-rc.1** + [[YAML]](https://github.com/camaraproject/EdgeApplicationManagement/blob/r1.2/code/API_definitions/edge-application-management.yaml) [[ReDoc]](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.2/code/API_definitions/edge-application-management.yaml&nocors) [[Swagger]](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/EdgeApplicationManagement/r1.2/code/API_definitions/edge-application-management.yaml) * For changes see [CHANGELOG](https://github.com/camaraproject/EdgeApplicationManagement/tree/main/CHANGELOG) diff --git a/code/API_definitions/edge-application-management.yaml b/code/API_definitions/edge-application-management.yaml index 12f7b10..d3e9da0 100644 --- a/code/API_definitions/edge-application-management.yaml +++ b/code/API_definitions/edge-application-management.yaml @@ -1,8 +1,7 @@ ---- openapi: 3.0.3 info: title: Edge Application Management - version: wip + version: 0.1.0-rc.1 description: | Edge Application Management API allows API consumers to manage the Life Cycle of an Application and to Discover Edge Cloud Zones. @@ -183,19 +182,12 @@ info: 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/EdgeApplicationManagement - servers: - - url: "{apiRoot}/edge-application-management/vwip" + - url: '{apiRoot}/edge-application-management/v0.1rc1' variables: apiRoot: default: http://localhost:9091 - description: - API root, defined by the service provider, e.g. `api.example.com` - or `api.example.com/somepath` - + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` tags: - name: Application description: Application and Application Instance Lice Cycle Management @@ -207,6 +199,9 @@ tags: description: Operations for handling application instance callback notifications - name: App Deployment CALLBACK Operation description: Operations for handling application deployment callback notifications +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/EdgeApplicationManagement paths: /apps: post: @@ -221,7 +216,7 @@ paths: instantiated in the Edge Cloud operationId: submitApp parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' requestBody: description: | The Application Provider request contains mandatory @@ -230,41 +225,41 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppManifest" + $ref: '#/components/schemas/AppManifest' required: true responses: - "201": + '201': description: Application created successfully headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/SubmittedApp" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "409": + $ref: '#/components/schemas/SubmittedApp' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '409': description: Conflict headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' example: status: 409 code: ALREADY_EXISTS - message: "App already exists" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + message: App already exists + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' get: security: - openId: @@ -277,31 +272,30 @@ paths: Edge Cloud Provider that the user has permission to view. operationId: getApps parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' responses: - "200": + '200': description: List of existing applications headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: type: array maxItems: 100 items: - $ref: "#/components/schemas/AppManifestInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" - + $ref: '#/components/schemas/AppManifestInfo' + '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' /apps/{appId}: get: security: @@ -314,7 +308,7 @@ paths: Ask the Edge Cloud Provider the information for a given application operationId: getApp parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appId description: | A globally unique identifier associated with the @@ -324,29 +318,29 @@ paths: in: path required: true schema: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' responses: - "200": + '200': description: Information of Application headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/AppManifestInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/AppManifestInfo' + '400': + $ref: '#/components/responses/Generic400' + '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: security: - openId: @@ -358,7 +352,7 @@ paths: description: Delete all the information and content related to an Application operationId: deleteApp parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appId in: path description: | @@ -367,44 +361,43 @@ paths: once the submission was successful required: true schema: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' responses: - "202": + '202': description: Request accepted headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "204": + $ref: '#/components/headers/x-correlator' + '204': description: App deleted headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "409": + $ref: '#/components/headers/x-correlator' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '409': description: Conflict headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' example: status: 409 code: INCOMPATIBLE_STATE - message: "App with a running application instance cannot be deleted" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" - + message: App with a running application instance cannot be deleted + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' /app-instances: post: security: @@ -418,7 +411,7 @@ paths: Edge Cloud Zone. operationId: createAppInstance parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' requestBody: description: | Information about the application and where to deploy it. @@ -432,22 +425,22 @@ paths: - edgeCloudZoneId properties: name: - $ref: "#/components/schemas/AppInstanceName" + $ref: '#/components/schemas/AppInstanceName' appId: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' kubernetesClusterRef: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' subscriptionRequest: - $ref: "#/components/schemas/SubscriptionRequest" + $ref: '#/components/schemas/SubscriptionRequest' required: true responses: - "202": + '202': description: Application instantiation accepted headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' Location: description: | Contains the URI of the newly created application instance, @@ -461,33 +454,33 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AppInstanceInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "409": + $ref: '#/components/schemas/AppInstanceInfo' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '409': description: Conflict headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' example: status: 409 code: ALREADY_EXISTS - message: "Application already instantiated in the given Edge Cloud Zone" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + message: Application already instantiated in the given Edge Cloud Zone + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' callbacks: onAppInstanceStatusChange: - $ref: "#/components/callbacks/onAppInstanceStatusChange" + $ref: '#/components/callbacks/onAppInstanceStatusChange' get: security: - openId: @@ -500,7 +493,7 @@ paths: given application operationId: getAppInstances parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appId description: | A globally unique identifier associated with @@ -510,7 +503,7 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' - name: region description: | Human readable name of the geographical Edge Cloud Region of @@ -518,33 +511,33 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudRegion" + $ref: '#/components/schemas/EdgeCloudRegion' responses: - "200": + '200': description: | List of application instances. Returns an empty list if no instances were found or none match the specified query parameters. headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: type: array maxItems: 100 items: - $ref: "#/components/schemas/AppInstanceInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/AppInstanceInfo' + '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' /app-instances/{appInstanceId}: get: security: @@ -558,7 +551,7 @@ paths: instance operationId: getAppInstance parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appInstanceId description: | A globally unique identifier associated with a running @@ -567,29 +560,29 @@ paths: in: path required: true schema: - $ref: "#/components/schemas/AppInstanceId" + $ref: '#/components/schemas/AppInstanceId' responses: - "200": + '200': description: Information of the Application Instance headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/AppInstanceInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/AppInstanceInfo' + '400': + $ref: '#/components/responses/Generic400' + '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: security: - openId: @@ -602,7 +595,7 @@ paths: an Edge Cloud Zone operationId: deleteAppInstance parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appInstanceId in: path description: | @@ -610,33 +603,32 @@ paths: that will be terminated required: true schema: - $ref: "#/components/schemas/AppInstanceId" + $ref: '#/components/schemas/AppInstanceId' responses: - "202": + '202': description: | Request accepted to be processed. It applies for async deletion process headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "204": + $ref: '#/components/headers/x-correlator' + '204': description: Application Instance Deleted headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" - + $ref: '#/components/headers/x-correlator' + '400': + $ref: '#/components/responses/Generic400' + '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' /deployments: post: security: @@ -650,7 +642,7 @@ paths: Edge Cloud Zones. operationId: createAppDeployment parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' requestBody: description: | Information about the application and where to deploy it. @@ -664,28 +656,28 @@ paths: - edgeCloudZones properties: appDeploymentName: - $ref: "#/components/schemas/AppDeploymentName" + $ref: '#/components/schemas/AppDeploymentName' appId: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' edgeCloudZones: type: array maxItems: 100 items: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' kubernetesClusterRefs: type: array maxItems: 100 items: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' subscriptionRequest: - $ref: "#/components/schemas/SubscriptionRequest" + $ref: '#/components/schemas/SubscriptionRequest' required: true responses: - "202": + '202': description: Application deployment accepted headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' Location: description: | Contains the URI of the newly created application deployment, @@ -702,33 +694,33 @@ paths: type: object properties: appDeploymentId: - $ref: "#/components/schemas/AppDeploymentId" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "409": + $ref: '#/components/schemas/AppDeploymentId' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '409': description: Conflict headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' example: status: 409 code: ALREADY_EXISTS - message: "Deployment already exists" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + message: Deployment already exists + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' callbacks: onAppDeploymentStatusChange: - $ref: "#/components/callbacks/onAppDeploymentStatusChange" + $ref: '#/components/callbacks/onAppDeploymentStatusChange' get: security: - openId: @@ -741,7 +733,7 @@ paths: given application operationId: getAppDeployments parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appId description: | A globally unique identifier associated with @@ -751,33 +743,33 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' responses: - "200": + '200': description: | List of application deployments. Returns an empty list if no deployments were found or none match the specified query parameters. headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: type: array maxItems: 100 items: - $ref: "#/components/schemas/AppDeploymentInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/AppDeploymentInfo' + '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' /deployments/{appDeploymentId}: get: security: @@ -791,7 +783,7 @@ paths: deployment operationId: getAppDeployment parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appDeploymentId description: | A globally unique identifier associated with a existing deployment @@ -800,29 +792,29 @@ paths: in: path required: true schema: - $ref: "#/components/schemas/AppDeploymentId" + $ref: '#/components/schemas/AppDeploymentId' responses: - "200": + '200': description: Information of the Application Deployment headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/AppDeploymentInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/AppDeploymentInfo' + '400': + $ref: '#/components/responses/Generic400' + '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: security: - openId: @@ -834,7 +826,7 @@ paths: Delete a deployment terminating all related instances of an application operationId: deleteAppDeployment parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appDeploymentId in: path description: | @@ -842,27 +834,27 @@ paths: that will be terminated required: true schema: - $ref: "#/components/schemas/AppDeploymentId" + $ref: '#/components/schemas/AppDeploymentId' responses: - "202": + '202': description: | Request accepted to be processed. It applies for async deletion process headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/headers/x-correlator' + '400': + $ref: '#/components/responses/Generic400' + '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' patch: security: - openId: @@ -881,14 +873,14 @@ paths: This operation may include changing the deployment name, target Edge Cloud Zones, or other updatable fields. operationId: updateAppDeployment parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: appDeploymentId in: path description: | Identifier of the specific application deployment to be updated. required: true schema: - $ref: "#/components/schemas/AppDeploymentId" + $ref: '#/components/schemas/AppDeploymentId' requestBody: description: | The fields to update for the application deployment using JSON Merge Patch (RFC 7396). @@ -904,17 +896,17 @@ paths: type: object properties: appDeploymentName: - $ref: "#/components/schemas/AppDeploymentName" + $ref: '#/components/schemas/AppDeploymentName' edgeCloudZones: type: array maxItems: 100 items: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' kubernetesClusterRefs: type: array maxItems: 100 items: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' examples: updateDeploymentName: summary: Update only the deployment name @@ -922,7 +914,7 @@ paths: This example shows how to update only the deployment name. Other fields will remain unchanged. value: - appDeploymentName: "my_updated_deployment" + appDeploymentName: my_updated_deployment updateMultipleFields: summary: Update multiple fields simultaneously description: | @@ -930,13 +922,13 @@ paths: and Edge Cloud Zones in a single request. Remember that both array fields will be completely replaced with the new values. value: - appDeploymentName: "production_deployment" + appDeploymentName: production_deployment edgeCloudZones: - - "123e4567-e89b-12d3-a456-426614174000" - - "123e4567-e89b-12d3-a456-426614174001" + - 123e4567-e89b-12d3-a456-426614174000 + - 123e4567-e89b-12d3-a456-426614174001 kubernetesClusterRefs: - - "642f6105-7015-4af1-a4d1-e1ecb8437abc" - - "642f6105-7015-4af1-a4d1-e1ecb8437def" + - 642f6105-7015-4af1-a4d1-e1ecb8437abc + - 642f6105-7015-4af1-a4d1-e1ecb8437def arrayReplacementExample: summary: Example of array replacement behavior description: | @@ -956,44 +948,43 @@ paths: To add a single zone while keeping existing ones, ALL zones must be included in the request. value: edgeCloudZones: - - "123e4567-e89b-12d3-a456-426614174000" - - "123e4567-e89b-12d3-a456-426614174003" + - 123e4567-e89b-12d3-a456-426614174000 + - 123e4567-e89b-12d3-a456-426614174003 responses: - "200": + '200': description: Application deployment updated successfully headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/AppDeploymentInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "404": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404" - "409": + $ref: '#/components/schemas/AppDeploymentInfo' + '400': + $ref: '#/components/responses/Generic400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '409': description: Conflict headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/ErrorInfo" + $ref: '#/components/schemas/ErrorInfo' example: status: 409 code: ABORTED - message: "Update conflict" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" - + message: Update conflict + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' /clusters: get: security: @@ -1008,7 +999,7 @@ paths: List available cluster information operationId: getClusters parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: region description: | Human readable name of the geographical Edge Cloud Region of @@ -1016,47 +1007,47 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudRegion" + $ref: '#/components/schemas/EdgeCloudRegion' - name: clusterRef description: | A globally unique identifier for the Cluster. in: query required: false schema: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' - name: edgeCloudZoneId description: | Edge Cloud Zone identifier. in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' responses: - "200": + '200': description: | Successful response, returning the cluster's information. Returns an empty list if no clusters were found or none match the specified query parameters. headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: type: array maxItems: 100 items: - $ref: "#/components/schemas/ClusterInfo" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/ClusterInfo' + '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' /edge-cloud-zones: get: security: @@ -1071,7 +1062,7 @@ paths: status (active/inactive/unknown) operationId: getEdgeCloudZones parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' - name: region description: | Human readable name of the geographical Edge Cloud Region of @@ -1079,35 +1070,35 @@ paths: in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudRegion" + $ref: '#/components/schemas/EdgeCloudRegion' - name: status description: Human readable status of the Edge Cloud Zone in: query required: false schema: - $ref: "#/components/schemas/EdgeCloudZoneStatus" + $ref: '#/components/schemas/EdgeCloudZoneStatus' responses: - "200": + '200': description: | Successful response, returning the Available Edge Cloud Zones. headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: "#/components/schemas/EdgeCloudZones" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "500": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500" - "503": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic503" + $ref: '#/components/schemas/EdgeCloudZones' + '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' components: securitySchemes: openId: @@ -1117,7 +1108,7 @@ components: notificationsBearerAuth: type: http scheme: bearer - bearerFormat: "{$request.body#/sinkCredential.credentialType}" + bearerFormat: '{$request.body#/sinkCredential.credentialType}' description: | Bearer token for notification delivery. Token format is determined by `sinkCredential.credentialType` in the subscription request. @@ -1128,17 +1119,14 @@ components: description: | Correlation id for the different services schema: - $ref: "#/components/schemas/XCorrelator" - + $ref: '#/components/schemas/XCorrelator' callbacks: onAppInstanceStatusChange: - "{$request.body#/subscriptionRequest/sink}": + '{$request.body#/subscriptionRequest/sink}': post: tags: - App Instance CALLBACK Operation - summary: - Provide a notification for a change in status of the instantiated - application + summary: Provide a notification for a change in status of the instantiated application description: | Instantiating an application is an asynchronous task. After the application status changes, the server will return a callback response at the specified URL. @@ -1146,7 +1134,7 @@ components: **WARNING**: This callback endpoint must be exposed on the listener side as `POST {$request.body#/subscriptionRequest/sink}` operationId: EdgeApplicationManagementCallback parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' security: - {} - notificationsBearerAuth: [] @@ -1156,31 +1144,29 @@ components: content: application/cloudevents+json: schema: - $ref: "#/components/schemas/CloudEvent" + $ref: '#/components/schemas/CloudEvent' responses: - "204": + '204': description: Successful notification - No Content headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "410": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic410" - "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" - + $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' onAppDeploymentStatusChange: - "{$request.body#/subscriptionRequest/sink}": + '{$request.body#/subscriptionRequest/sink}': post: tags: - App Deployment CALLBACK Operation - summary: Provide a notification for a change in status of the deployed - application + summary: Provide a notification for a change in status of the deployed application description: | Deploying an application is an asynchronous task. After the application deployment status changes, the server will return a callback response at the specified URL. @@ -1188,7 +1174,7 @@ components: **WARNING**: This callback endpoint must be exposed on the listener side as `POST {$request.body#/subscriptionRequest/sink}` operationId: EdgeApplicationManagementDeploymentCallback parameters: - - $ref: "#/components/parameters/x-correlator" + - $ref: '#/components/parameters/x-correlator' security: - {} - notificationsBearerAuth: [] @@ -1198,39 +1184,33 @@ components: content: application/cloudevents+json: schema: - $ref: "#/components/schemas/CloudEvent" + $ref: '#/components/schemas/CloudEvent' responses: - "204": + '204': description: Successful notification - No Content headers: x-correlator: - $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" - "400": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400" - "401": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401" - "403": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403" - "410": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic410" - "429": - $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429" - + $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' schemas: AccessTokenCredential: type: object - description: - An access token credential. This type of credential is meant to be - used by API Consumers that have limited capabilities to handle - authorization requests. + description: An access token credential. This type of credential is meant to be used by API Consumers that have limited capabilities to handle authorization requests. allOf: - - $ref: "#/components/schemas/SinkCredential" + - $ref: '#/components/schemas/SinkCredential' - type: object properties: accessToken: - description: - Access Token granting access to the POST operation to create - notification + description: Access Token granting access to the POST operation to create notification type: string writeOnly: true maxLength: 4096 @@ -1245,7 +1225,7 @@ components: existence. If the token expires while the resource is still active, the client will stop receiving notifications. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - example: "2023-07-03T12:27:08.312Z" + example: '2023-07-03T12:27:08.312Z' accessTokenType: description: Type of access token - MUST be set to bearer for now type: string @@ -1256,10 +1236,48 @@ components: - accessToken - accessTokenExpiresUtc - accessTokenType - CloudEvent: - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/CloudEvent" - + type: object + description: | + CloudEvents 1.0 specification envelope. + This schema is the stable base for all CAMARA event notifications. + It imposes no constraints on `type` values or `data` structure — + those concerns belong to the API-specific and lifecycle group schemas. + required: + - id + - source + - specversion + - type + - time + properties: + id: + type: string + maxLength: 256 + description: Identifier of this event, unique within the source context. + source: + $ref: '#/components/schemas/Source' + type: + type: string + maxLength: 512 + description: | + Identifies the event type. CAMARA APIs use reverse-DNS notation: + `org.camaraproject...` + The api-name segment makes each type globally unique across API groups. + 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: + type: object + description: Event details payload. Structure is defined by each concrete event schema. + time: + $ref: '#/components/schemas/DateTime' SubscriptionEventType: type: string description: | @@ -1268,11 +1286,8 @@ components: - org.camaraproject.edge-application-management.v0.app-instance-status-change - org.camaraproject.edge-application-management.v0.app-deployment-status-change - org.camaraproject.edge-application-management.v0.subscription-ended - SubscriptionRequest: - description: - The request for creating an event-type event subscription (implicit - subscription, HTTP only) + description: The request for creating an event-type event subscription (implicit subscription, HTTP only) type: object required: - sink @@ -1282,12 +1297,10 @@ components: format: uri pattern: ^https:\/\/.+$ maxLength: 2048 - description: - The address to which events shall be delivered using the selected - protocol. - example: "https://endpoint.example.com/sink" + description: The address to which events shall be delivered using the selected protocol. + example: https://endpoint.example.com/sink sinkCredential: - $ref: "#/components/schemas/SinkCredential" + $ref: '#/components/schemas/SinkCredential' types: description: | Camara Event types eligible to be delivered by this subscription. @@ -1296,10 +1309,9 @@ components: minItems: 1 maxItems: 1 items: - $ref: "#/components/schemas/SubscriptionEventType" + $ref: '#/components/schemas/SubscriptionEventType' config: - $ref: "#/components/schemas/SubscriptionConfig" - + $ref: '#/components/schemas/SubscriptionConfig' SubscriptionConfig: description: | Implementation-specific configuration parameters needed by the subscription manager for acquiring events. @@ -1317,19 +1329,12 @@ components: type: string maxLength: 64 format: date-time - example: 2023-01-17T13:18:23.682Z - description: - The subscription expiration time (in date-time format) requested by - the API consumer. It must follow [RFC - 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and - must have time zone. + example: '2023-01-17T13:18:23.682Z' + description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. subscriptionMaxEvents: type: integer format: int32 - 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. + 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. minimum: 1 maximum: 2147483647 example: 5 @@ -1338,10 +1343,8 @@ components: 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: If initialEvent is set to true and application is in a specific status, an event is triggered. - SinkCredential: - description: A sink credential provides authentication or authorization - information necessary to enable delivery of events to a target. + description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. type: object required: - credentialType @@ -1354,8 +1357,7 @@ components: discriminator: propertyName: credentialType mapping: - ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" - + ACCESSTOKEN: '#/components/schemas/AccessTokenCredential' AccessEndpoint: type: object description: | @@ -1372,24 +1374,23 @@ components: - ipv6Addresses properties: port: - $ref: "#/components/schemas/Port" + $ref: '#/components/schemas/Port' fqdn: - $ref: "#/components/schemas/Fqdn" + $ref: '#/components/schemas/Fqdn' ipv4Addresses: description: IP version 4 of an application instance type: array items: - $ref: "#/components/schemas/Ipv4Addr" + $ref: '#/components/schemas/Ipv4Addr' minItems: 1 maxItems: 16 ipv6Addresses: description: IP version 6 of an application instance. type: array items: - $ref: "#/components/schemas/Ipv6Addr" + $ref: '#/components/schemas/Ipv6Addr' minItems: 1 maxItems: 16 - AppId: type: string format: uuid @@ -1400,7 +1401,6 @@ components: A globally unique identifier associated with the application. Edge Cloud Platform generates this identifier when the Application is submitted. - AppInstanceId: type: string format: uuid @@ -1412,7 +1412,6 @@ components: instance of an application. Edge Cloud Platform generates this identifier when the instantiation in the Edge Cloud Zone is successful. - AppDeploymentId: type: string format: uuid @@ -1423,7 +1422,6 @@ components: A globally unique identifier associated with a existing deployment of an application. Edge Cloud Platform generates this identifier when the deployment request in the Edge Cloud Zone is successful. - AppDeploymentInfo: description: Information about the application deployment. type: object @@ -1435,26 +1433,25 @@ components: - appInstances properties: appDeploymentName: - $ref: "#/components/schemas/AppDeploymentName" + $ref: '#/components/schemas/AppDeploymentName' appDeploymentId: - $ref: "#/components/schemas/AppDeploymentId" + $ref: '#/components/schemas/AppDeploymentId' appId: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' edgeCloudZones: description: | List of Edge Cloud Zones where the application is deployed. type: array maxItems: 100 items: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' appInstances: description: | List of application instances created as part of this deployment. type: array maxItems: 100 items: - $ref: "#/components/schemas/AppInstanceId" - + $ref: '#/components/schemas/AppInstanceId' AppInstanceInfo: description: Information about the application instance. type: object @@ -1466,13 +1463,13 @@ components: - edgeCloudZoneId properties: name: - $ref: "#/components/schemas/AppInstanceName" + $ref: '#/components/schemas/AppInstanceName' appId: - $ref: "#/components/schemas/AppId" + $ref: '#/components/schemas/AppId' appInstanceId: - $ref: "#/components/schemas/AppInstanceId" + $ref: '#/components/schemas/AppInstanceId' appProvider: - $ref: "#/components/schemas/AppProvider" + $ref: '#/components/schemas/AppProvider' status: description: Status of the application instance (default is 'unknown') type: string @@ -1503,27 +1500,24 @@ components: - accessPoints properties: interfaceId: - $ref: "#/components/schemas/InterfaceId" + $ref: '#/components/schemas/InterfaceId' accessPoints: - $ref: "#/components/schemas/AccessEndpoint" + $ref: '#/components/schemas/AccessEndpoint' minItems: 1 kubernetesClusterRef: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" - + $ref: '#/components/schemas/EdgeCloudZoneId' AppInstanceName: type: string maxLength: 64 pattern: ^[A-Za-z][A-Za-z0-9_]{1,63}$ description: Name of the App instance, scoped to the AppProvider - AppDeploymentName: type: string maxLength: 64 pattern: ^[A-Za-z][A-Za-z0-9_]{1,63}$ description: Name of the App Deployment, scoped to the AppProvider - AppManifest: type: object description: | @@ -1536,7 +1530,7 @@ components: pattern: ^[A-Za-z][A-Za-z0-9_]{1,63}$ description: Name of the application. appProvider: - $ref: "#/components/schemas/AppProvider" + $ref: '#/components/schemas/AppProvider' version: type: string maxLength: 64 @@ -1551,7 +1545,7 @@ components: - HELM - CSAR operatingSystem: - $ref: "#/components/schemas/OperatingSystem" + $ref: '#/components/schemas/OperatingSystem' appRepo: description: | Repository where Application Provider stores the application image @@ -1574,7 +1568,7 @@ components: recommended to be the personal access token created by developer e.g. in Github repo. imagePath: - $ref: "#/components/schemas/Uri" + $ref: '#/components/schemas/Uri' userName: type: string maxLength: 64 @@ -1603,12 +1597,12 @@ components: checksum: type: string maxLength: 128 - pattern: "^(?:[A-Fa-f0-9]{32}|[A-Fa-f0-9]{64})$" + pattern: ^(?:[A-Fa-f0-9]{32}|[A-Fa-f0-9]{64})$ description: | MD5 checksum for VM and file-based images, sha256 digest for containers requiredResources: - $ref: "#/components/schemas/RequiredResources" + $ref: '#/components/schemas/RequiredResources' componentSpec: description: | Information defined in "appRepo" point to the application @@ -1660,7 +1654,7 @@ components: - visibilityType properties: interfaceId: - $ref: "#/components/schemas/InterfaceId" + $ref: '#/components/schemas/InterfaceId' protocol: type: string enum: @@ -1671,7 +1665,7 @@ components: Defines the IP transport communication protocol i.e., TCP, UDP or ANY port: - $ref: "#/components/schemas/Port" + $ref: '#/components/schemas/Port' visibilityType: description: | Defines whether the interface is exposed @@ -1695,27 +1689,24 @@ components: - appRepo - requiredResources - componentSpec - AppManifestInfo: description: | Application information as returned by the Edge Cloud Provider, including the appId assigned once the application has been submitted. allOf: - - $ref: "#/components/schemas/AppManifest" + - $ref: '#/components/schemas/AppManifest' - type: object required: - appId properties: appId: - $ref: "#/components/schemas/AppId" - + $ref: '#/components/schemas/AppId' AppProvider: type: string maxLength: 64 pattern: ^[A-Za-z][A-Za-z0-9_]{7,63}$ description: Human readable name of the Application Provider. - ClusterInfo: type: object description: Kubernetes cluster information @@ -1731,13 +1722,13 @@ components: description: | Name of the Cluster, scoped to the Provider provider: - $ref: "#/components/schemas/AppProvider" + $ref: '#/components/schemas/AppProvider' clusterRef: - $ref: "#/components/schemas/KubernetesClusterRef" + $ref: '#/components/schemas/KubernetesClusterRef' edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' edgeCloudRegion: - $ref: "#/components/schemas/EdgeCloudRegion" + $ref: '#/components/schemas/EdgeCloudRegion' version: type: string maxLength: 64 @@ -1748,31 +1739,27 @@ components: type: array maxItems: 100 items: - $ref: "#/components/schemas/KubernetesNodePool" + $ref: '#/components/schemas/KubernetesNodePool' minItems: 1 - EdgeCloudProvider: type: string maxLength: 64 description: Human readable name of the Edge Cloud Provider. - EdgeCloudRegion: type: string maxLength: 64 description: | Human readable name of the geographical Edge Cloud Region of the Edge Cloud. Defined by the Edge Cloud Provider. - EdgeCloudZones: type: array items: - $ref: "#/components/schemas/EdgeCloudZone" + $ref: '#/components/schemas/EdgeCloudZone' minItems: 1 maxItems: 100 description: | A collection of Edge Cloud Zones where the Application Provider can instantiate an Application Instance. - EdgeCloudZoneId: type: string format: uuid @@ -1782,7 +1769,6 @@ components: description: | Unique identifier created by the Edge Cloud Platform to identify an Edge Cloud Zone within an Edge Cloud. - EdgeCloudZone: type: object description: | @@ -1797,23 +1783,21 @@ components: - edgeCloudProvider properties: edgeCloudZoneId: - $ref: "#/components/schemas/EdgeCloudZoneId" + $ref: '#/components/schemas/EdgeCloudZoneId' edgeCloudZoneName: - $ref: "#/components/schemas/EdgeCloudZoneName" + $ref: '#/components/schemas/EdgeCloudZoneName' edgeCloudZoneStatus: - $ref: "#/components/schemas/EdgeCloudZoneStatus" + $ref: '#/components/schemas/EdgeCloudZoneStatus' edgeCloudProvider: - $ref: "#/components/schemas/EdgeCloudProvider" + $ref: '#/components/schemas/EdgeCloudProvider' edgeCloudRegion: - $ref: "#/components/schemas/EdgeCloudRegion" - + $ref: '#/components/schemas/EdgeCloudRegion' EdgeCloudZoneName: type: string maxLength: 64 description: | Human readable name of the geographical zone of the Edge Cloud. Defined by the Edge Cloud Provider. - EdgeCloudZoneStatus: description: Status of the Edge Cloud Zone (default is 'unknown') type: string @@ -1822,17 +1806,34 @@ components: - inactive - unknown default: unknown - ErrorInfo: - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" - + type: object + description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message + required: + - status + - code + - message + properties: + status: + type: integer + format: int32 + minimum: 100 + maximum: 599 + description: HTTP response status code + code: + type: string + maxLength: 96 + description: A human-readable code to describe the error + message: + type: string + maxLength: 512 + description: A human-readable description of what the event represents Fqdn: type: string format: hostname maxLength: 253 description: | Full qualified domain name of an application instance - GpuInfo: type: object description: Information about the supported GPUs @@ -1852,7 +1853,6 @@ components: minimum: 0 maximum: 16 description: Number of GPUs - K8sAddons: description: | Addons for the Kubernetes cluster. @@ -1869,7 +1869,6 @@ components: enum: - monitoring - ingress - K8sNetworking: description: | Kubernetes networking definition @@ -1890,7 +1889,7 @@ components: description: CNI provider version type: string maxLength: 64 - example: "1.13" + example: '1.13' additionalNetworks: description: Additional Networks for the Kubernetes cluster. type: array @@ -1921,7 +1920,6 @@ components: - netdevice - vfio-pci - interface - AdditionalStorage: description: Additional storage for the application. type: array @@ -1950,7 +1948,6 @@ components: maxLength: 64 description: Location of additional storage resource. example: /logs - Vcpu: type: string maxLength: 16 @@ -1958,8 +1955,7 @@ components: description: | Number of vcpus in whole (i.e 1), decimal (i.e 0.500) up to millivcpu, or millivcpu (i.e 500m) format. - example: "500m" - + example: 500m KubernetesClusterRef: description: | A global unique identifier associated with a Kubernetes cluster @@ -1969,8 +1965,7 @@ components: pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ minLength: 36 maxLength: 36 - example: "642f6105-7015-4af1-a4d1-e1ecb8437abc" - + example: 642f6105-7015-4af1-a4d1-e1ecb8437abc KubernetesNodePool: type: object description: | @@ -2022,7 +2017,6 @@ components: minimum: 1 maximum: 16384 example: 4096 - KubernetesResources: type: object description: Definition of Kubernetes Cluster Infrastructure. @@ -2218,10 +2212,9 @@ components: example: 80GB pattern: ^\d+(GB|MB)$ networking: - $ref: "#/components/schemas/K8sNetworking" + $ref: '#/components/schemas/K8sNetworking' addons: - $ref: "#/components/schemas/K8sAddons" - + $ref: '#/components/schemas/K8sAddons' VmResources: description: Definition of Virtual Machine Infrastructure type: object @@ -2252,10 +2245,9 @@ components: example: 1024 description: Memory in mega bytes additionalStorages: - $ref: "#/components/schemas/AdditionalStorage" + $ref: '#/components/schemas/AdditionalStorage' gpu: - $ref: "#/components/schemas/GpuInfo" - + $ref: '#/components/schemas/GpuInfo' DockerComposeResources: description: Definition of Docker Compose Infrastructure type: object @@ -2286,10 +2278,9 @@ components: example: 1024 description: Memory in mega bytes storage: - $ref: "#/components/schemas/AdditionalStorage" + $ref: '#/components/schemas/AdditionalStorage' gpu: - $ref: "#/components/schemas/GpuInfo" - + $ref: '#/components/schemas/GpuInfo' ContainerResources: description: Container Infrastructure Definition type: object @@ -2305,7 +2296,7 @@ components: enum: - container numCPU: - $ref: "#/components/schemas/Vcpu" + $ref: '#/components/schemas/Vcpu' memory: type: integer format: int32 @@ -2314,10 +2305,9 @@ components: example: 1024 description: Memory in mega bytes storage: - $ref: "#/components/schemas/AdditionalStorage" + $ref: '#/components/schemas/AdditionalStorage' gpu: - $ref: "#/components/schemas/GpuInfo" - + $ref: '#/components/schemas/GpuInfo' InterfaceId: type: string minLength: 4 @@ -2326,26 +2316,23 @@ components: description: | This is the interface Identifier that Application Provider defines when application is being submitted. - Ipv4Addr: type: string maxLength: 15 format: ipv4 - example: "192.168.0.1" + example: 192.168.0.1 description: | IP of the device. A single IPv4 address may be specified in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - Ipv6Addr: type: string maxLength: 45 format: ipv6 - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 description: | IP of the device. A single IPv6 address, following IETF 5952 format, may be specified like 2001:db8:85a3:8d3:1319:8a2e:370:7344 - OperatingSystem: description: | Information about the Operating System of the application image @@ -2387,38 +2374,34 @@ components: - OS_LICENSE_TYPE_FREE - OS_LICENSE_TYPE_ON_DEMAND - OTHER - Port: type: integer description: Port to stablish the connection format: int32 minimum: 1 maximum: 65535 - RequiredResources: description: | Fundamental hardware requirements to be provisioned by the Application Provider. oneOf: - - $ref: "#/components/schemas/KubernetesResources" - - $ref: "#/components/schemas/VmResources" - - $ref: "#/components/schemas/ContainerResources" - - $ref: "#/components/schemas/DockerComposeResources" + - $ref: '#/components/schemas/KubernetesResources' + - $ref: '#/components/schemas/VmResources' + - $ref: '#/components/schemas/ContainerResources' + - $ref: '#/components/schemas/DockerComposeResources' discriminator: propertyName: infraKind mapping: - kubernetes: "#/components/schemas/KubernetesResources" - virtualMachine: "#/components/schemas/VmResources" - container: "#/components/schemas/ContainerResources" - dockerCompose: "#/components/schemas/DockerComposeResources" - + kubernetes: '#/components/schemas/KubernetesResources' + virtualMachine: '#/components/schemas/VmResources' + container: '#/components/schemas/ContainerResources' + dockerCompose: '#/components/schemas/DockerComposeResources' SubmittedApp: description: Information about the submitted app type: object properties: appId: - $ref: "#/components/schemas/AppId" - + $ref: '#/components/schemas/AppId' Uri: type: string format: uri @@ -2428,6 +2411,265 @@ components: A Uniform Resource Identifier (URI) as per RFC 3986, identifies the endpoint within an Edge Cloud Zone where the user equipment may connect to the selected application instance - XCorrelator: - $ref: "../common/CAMARA_common.yaml#/components/schemas/XCorrelator" + type: string + description: Correlator string, UUID format recommended but any string matching the pattern can be used + pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 + example: b4333c46-49c0-4f62-80d7-f0ef930f1c46 + Source: + type: string + format: uri-reference + minLength: 1 + maxLength: 2048 + description: | + Identifies the context in which an event happened - be 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.example.com + DateTime: + type: string + format: date-time + maxLength: 64 + description: Timestamp. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + example: '2018-04-05T17:31:00Z' + headers: + x-correlator: + description: Correlation id for the different services + schema: + $ref: '#/components/schemas/XCorrelator' + responses: + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - OUT_OF_RANGE + 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: Unauthorized + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - UNAUTHENTICATED + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated and a new authentication is required + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + - INVALID_TOKEN_CONTEXT + 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: Request body is not consistent with access token. + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 500 + code: + enum: + - INTERNAL + 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 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 503 + code: + enum: + - 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. + Generic404: + description: Not found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - NOT_FOUND + - IDENTIFIER_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_IDENTIFIER_NOT_FOUND: + description: Some identifier cannot be matched to a device + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. + Generic410: + description: Gone + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 410 + code: + enum: + - GONE + 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. + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 429 + code: + enum: + - QUOTA_EXCEEDED + - TOO_MANY_REQUESTS + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Out of resource quota. + GENERIC_429_TOO_MANY_REQUESTS: + description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Rate limit reached. diff --git a/code/Test_definitions/edge-application-management-createAppDeployment.feature b/code/Test_definitions/edge-application-management-createAppDeployment.feature index 2b88ab1..2f26a74 100644 --- a/code/Test_definitions/edge-application-management-createAppDeployment.feature +++ b/code/Test_definitions/edge-application-management-createAppDeployment.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation createAppDeployment +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation createAppDeployment # Input to be provided by the implementation to the tester # # Implementation indications: @@ -11,7 +11,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation createAppDeplo # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common createAppDeployment setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/deployments" + And the resource "/edge-application-management/v0.1rc1/deployments" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-createAppInstance.feature b/code/Test_definitions/edge-application-management-createAppInstance.feature index d38051a..bf05788 100644 --- a/code/Test_definitions/edge-application-management-createAppInstance.feature +++ b/code/Test_definitions/edge-application-management-createAppInstance.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation createAppInstance +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation createAppInstance # Input to be provided by the implementation to the tester # # Implementation indications: @@ -11,7 +11,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation createAppInsta # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common createAppInstance setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/app-instances" + And the resource "/edge-application-management/v0.1rc1/app-instances" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-deleteApp.feature b/code/Test_definitions/edge-application-management-deleteApp.feature index 60347fe..0194a36 100644 --- a/code/Test_definitions/edge-application-management-deleteApp.feature +++ b/code/Test_definitions/edge-application-management-deleteApp.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation deleteApp +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation deleteApp # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation deleteApp # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common deleteApp setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/apps/{appId}" + And the resource "/edge-application-management/v0.1rc1/apps/{appId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-deleteAppDeployment.feature b/code/Test_definitions/edge-application-management-deleteAppDeployment.feature index 8a798cb..3f1efa7 100644 --- a/code/Test_definitions/edge-application-management-deleteAppDeployment.feature +++ b/code/Test_definitions/edge-application-management-deleteAppDeployment.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation deleteAppDeployment +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation deleteAppDeployment # Input to be provided by the implementation to the tester # # Implementation indications: @@ -11,7 +11,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation deleteAppDeplo # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common deleteAppDeployment setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/deployments/{appDeploymentId}" + And the resource "/edge-application-management/v0.1rc1/deployments/{appDeploymentId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-deleteAppInstance.feature b/code/Test_definitions/edge-application-management-deleteAppInstance.feature index 3efbdb5..25159e8 100644 --- a/code/Test_definitions/edge-application-management-deleteAppInstance.feature +++ b/code/Test_definitions/edge-application-management-deleteAppInstance.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation deleteAppInstance +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation deleteAppInstance # Input to be provided by the implementation to the tester # # Implementation indications: @@ -11,7 +11,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation deleteAppInsta # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common deleteAppInstance setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/app-instances" + And the resource "/edge-application-management/v0.1rc1/app-instances" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getApp.feature b/code/Test_definitions/edge-application-management-getApp.feature index dc07aff..65ae1c1 100644 --- a/code/Test_definitions/edge-application-management-getApp.feature +++ b/code/Test_definitions/edge-application-management-getApp.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getApp +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getApp # Input to be provided by the implementation to the tester # # Implementation indications: @@ -12,7 +12,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getApp Background: Common getApp setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/apps/{appId}" + And the resource "/edge-application-management/v0.1rc1/apps/{appId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getAppDeployment.feature b/code/Test_definitions/edge-application-management-getAppDeployment.feature index 6efa6f9..79f9d51 100644 --- a/code/Test_definitions/edge-application-management-getAppDeployment.feature +++ b/code/Test_definitions/edge-application-management-getAppDeployment.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getAppDeployment +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getAppDeployment # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getAppDeployme # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getAppDeployment setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/deployments/{appDeploymentId}" + And the resource "/edge-application-management/v0.1rc1/deployments/{appDeploymentId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getAppDeployments.feature b/code/Test_definitions/edge-application-management-getAppDeployments.feature index 2764a0e..52fbca5 100644 --- a/code/Test_definitions/edge-application-management-getAppDeployments.feature +++ b/code/Test_definitions/edge-application-management-getAppDeployments.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getAppDeployments +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getAppDeployments # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getAppDeployme # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getAppDeployments setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/deployments" + And the resource "/edge-application-management/v0.1rc1/deployments" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getAppInstance.feature b/code/Test_definitions/edge-application-management-getAppInstance.feature index 9be27f9..251de95 100644 --- a/code/Test_definitions/edge-application-management-getAppInstance.feature +++ b/code/Test_definitions/edge-application-management-getAppInstance.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getAppInstance +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getAppInstance # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getAppInstance # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getAppInstance setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/app-instances/{appInstanceId}" + And the resource "/edge-application-management/v0.1rc1/app-instances/{appInstanceId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getAppInstances.feature b/code/Test_definitions/edge-application-management-getAppInstances.feature index 3e0a815..2f8557f 100644 --- a/code/Test_definitions/edge-application-management-getAppInstances.feature +++ b/code/Test_definitions/edge-application-management-getAppInstances.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getAppInstances +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getAppInstances # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getAppInstance # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getAppInstances setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/app-instances" + And the resource "/edge-application-management/v0.1rc1/app-instances" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getApps.feature b/code/Test_definitions/edge-application-management-getApps.feature index 16b319b..7dd168b 100644 --- a/code/Test_definitions/edge-application-management-getApps.feature +++ b/code/Test_definitions/edge-application-management-getApps.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operations getApps +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operations getApps # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operations getApps # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getApps setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/apps" + And the resource "/edge-application-management/v0.1rc1/apps" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getClusters.feature b/code/Test_definitions/edge-application-management-getClusters.feature index 7b6f57d..5b11603 100644 --- a/code/Test_definitions/edge-application-management-getClusters.feature +++ b/code/Test_definitions/edge-application-management-getClusters.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getClusters +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getClusters # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getClusters # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getClusters setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/clusters" + And the resource "/edge-application-management/v0.1rc1/clusters" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature b/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature index 6da9841..95fea4d 100644 --- a/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature +++ b/code/Test_definitions/edge-application-management-getEdgeCloudZones.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation getEdgeCloudZones +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation getEdgeCloudZones # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation getEdgeCloudZo # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common getEdgeCloudZones setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/edge-cloud-zones" + And the resource "/edge-application-management/v0.1rc1/edge-cloud-zones" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-submitApp.feature b/code/Test_definitions/edge-application-management-submitApp.feature index e761478..868881e 100644 --- a/code/Test_definitions/edge-application-management-submitApp.feature +++ b/code/Test_definitions/edge-application-management-submitApp.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation submitApp +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation submitApp # Input to be provided by the implementation to the tester # # Implementation indications: @@ -10,7 +10,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation submitApp # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common submitApp setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/apps" + And the resource "/edge-application-management/v0.1rc1/apps" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_definitions/edge-application-management-updateAppDeployment.feature b/code/Test_definitions/edge-application-management-updateAppDeployment.feature index f75ebc3..a705a9a 100644 --- a/code/Test_definitions/edge-application-management-updateAppDeployment.feature +++ b/code/Test_definitions/edge-application-management-updateAppDeployment.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Edge Application Management API, vwip - Operation updateAppDeployment +Feature: CAMARA Edge Application Management API, v0.1.0-rc.1 - Operation updateAppDeployment # Input to be provided by the implementation to the tester # # Implementation indications: @@ -11,7 +11,7 @@ Feature: CAMARA Edge Application Management API, vwip - Operation updateAppDeplo # References to OAS spec schemas refer to schemas specified in edge-application-management.yaml Background: Common updateAppDeployment setup Given an environment at "apiRoot" - And the resource "/edge-application-management/vwip/deployments/{appDeploymentId}" + And the resource "/edge-application-management/v0.1rc1/deployments/{appDeploymentId}" 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" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/common/.sync-manifest.yaml b/code/common/.sync-manifest.yaml deleted file mode 100644 index 0de41d2..0000000 --- a/code/common/.sync-manifest.yaml +++ /dev/null @@ -1,7 +0,0 @@ -sources: -- repository: Commonalities - release: r4.3 - files: - CAMARA_common.yaml: 73895974478c1d8fffd2ba7b7a6553eec1a145b1 - CAMARA_event_common.yaml: 42e72db4f3e8562b93b54b6182c40afb2b850d48 - info-description-templates.yaml: 1c7928d2cf51c70b8cdea7b4e5fdbaa75f7d984b diff --git a/code/common/CAMARA_common.yaml b/code/common/CAMARA_common.yaml deleted file mode 100644 index 7389597..0000000 --- a/code/common/CAMARA_common.yaml +++ /dev/null @@ -1,931 +0,0 @@ -info: - title: CAMARA common data types - description: | - Common data types for CAMARA APIs. - This file contains Commonalities-owned schemas that are identical across all - CAMARA APIs, including error responses, common parameters, headers, and - reusable data types. - - API repositories place this file in `code/common/` and reference schemas - via `$ref: "../common/CAMARA_common.yaml#/components/schemas/"`. - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip - x-camara-commonalities: 0.8.0 - -components: - securitySchemes: - openId: - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration - description: OpenID Connect authentication via discovery metadata. - - headers: - x-correlator: - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" - - x-total-count: - description: Total number of items. Mirrors `pagination.totalCount` in the response body. - required: false - schema: - $ref: "#/components/schemas/TotalCount" - - x-total-pages: - description: Total number of pages. Mirrors `pagination.totalPages` in the response body. - required: false - schema: - $ref: "#/components/schemas/TotalPages" - - link: - description: | - Navigation links for paginated results following - [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288). - Includes only the rels applicable to the current position - (`first`, `prev`, `next`, `last`). All original query parameters - are preserved in Link URLs. - Example: - Link: ; rel="first", - ; rel="prev", - ; rel="next", - ; rel="last" - required: false - schema: - type: string - maxLength: 8192 - - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" - - page: - name: page - in: query - description: > - Requested page number. Pages are 1-indexed. - Values below 1 are rejected with `400 INVALID_ARGUMENT`. - required: false - schema: - $ref: "#/components/schemas/Page" - - perPage: - name: perPage - in: query - description: > - Number of subscriptions to return per page. - Values outside the allowed range are rejected with `400 INVALID_ARGUMENT`. - required: false - schema: - $ref: "#/components/schemas/PerPage" - - schemas: - XCorrelator: - type: string - description: Correlator string, UUID format recommended but any string matching the pattern can be used - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - maxLength: 256 - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" - DateTime: - type: string - format: date-time - maxLength: 64 - description: Timestamp. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - example: "2018-04-05T17:31:00Z" - TimePeriod: - type: object - description: A period of time defined by a start date and an optional end date. If `endDate` is not included, then the period has no ending date. - properties: - startDate: - $ref: "#/components/schemas/DateTime" - endDate: - $ref: "#/components/schemas/DateTime" - required: - - startDate - ErrorInfo: - type: object - description: A structured error response providing details about a failed request, including the HTTP status code, an error code, and a human-readable message - required: - - status - - code - - message - properties: - status: - type: integer - format: int32 - minimum: 100 - maximum: 599 - description: HTTP response status code - code: - type: string - maxLength: 96 - description: A human-readable code to describe the error - message: - type: string - maxLength: 512 - description: A human-readable description of what the event represents - 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 network operator might support only a subset of these options. The API Consumer can provide multiple identifiers to ensure compatibility across different network operators. In this case, the API Provider will use one of the identifiers for the API logic without performing any matching checks among the provided identifiers. - NOTE2: as for this Commonalities release, 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/DeviceIpv4Address" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - minProperties: 1 - - DeviceResponse: - description: | - An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response. - - If the API consumer provides more than one device identifier in their request, and this schema is included in the response definition, the API provider MUST use it to return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user. - - allOf: - - $ref: "#/components/schemas/Device" - - maxProperties: 1 - - 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, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - maxLength: 16 - example: "+123456789" - - 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 - maxLength: 2048 - example: "123456789@example.com" - - DeviceIpv4Address: - 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/SingleIpv4Address" - privateAddress: - $ref: "#/components/schemas/SingleIpv4Address" - publicPort: - $ref: "#/components/schemas/Port" - anyOf: - - required: [publicAddress, privateAddress] - - required: [publicAddress, publicPort] - example: - publicAddress: "84.125.93.10" - publicPort: 59765 - - SingleIpv4Address: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - maxLength: 15 - example: "84.125.93.10" - - Port: - description: TCP or UDP port number - type: integer - format: int32 - minimum: 1 - maximum: 65535 - - 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). - type: string - format: ipv6 - maxLength: 45 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - Area: - description: Base schema for all areas - type: object - properties: - areaType: - $ref: "#/components/schemas/AreaType" - required: - - areaType - discriminator: - propertyName: areaType - mapping: - CIRCLE: "#/components/schemas/Circle" - POLYGON: "#/components/schemas/Polygon" - - AreaType: - type: string - description: | - Type of this area. - CIRCLE - The area is defined as a circle. - POLYGON - The area is defined as a polygon. - enum: - - CIRCLE - - POLYGON - - Circle: - description: Circular area - allOf: - - $ref: "#/components/schemas/Area" - - type: object - required: - - center - - radius - properties: - center: - $ref: "#/components/schemas/Point" - radius: - type: number - description: Distance from the center in meters - minimum: 1 - - Polygon: - description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. - allOf: - - $ref: "#/components/schemas/Area" - - type: object - required: - - boundary - properties: - boundary: - $ref: "#/components/schemas/PointList" - - PointList: - description: List of points defining a polygon - type: array - items: - $ref: "#/components/schemas/Point" - minItems: 3 - maxItems: 15 - - Point: - type: object - description: Coordinates (latitude, longitude) defining a location in a map - required: - - latitude - - longitude - properties: - latitude: - $ref: "#/components/schemas/Latitude" - longitude: - $ref: "#/components/schemas/Longitude" - example: - latitude: 50.735851 - longitude: 7.10066 - - Latitude: - description: Latitude component of a location - type: number - format: double - minimum: -90 - maximum: 90 - - Longitude: - description: Longitude component of location - type: number - format: double - minimum: -180 - maximum: 180 - - # ───────────────────────────────────────────────────────────────────────── - # Pagination - # ───────────────────────────────────────────────────────────────────────── - - Pagination: - description: Pagination details helping to navigate through paged results efficiently. - type: object - properties: - page: - $ref: "#/components/schemas/Page" - perPage: - $ref: "#/components/schemas/PerPage" - totalCount: - $ref: "#/components/schemas/TotalCount" - totalPages: - $ref: "#/components/schemas/TotalPages" - - Page: - type: integer - format: int32 - minimum: 1 - maximum: 2147483647 - default: 1 - description: Current page number (1-indexed). - example: 1 - PerPage: - type: integer - format: int32 - minimum: 1 - maximum: 100 - default: 20 - description: Number of items per page. - example: 20 - TotalCount: - type: integer - format: int32 - minimum: 0 - maximum: 2147483647 - description: Total number of items matching the query, after filters applied. MAY be omitted where a full count query is prohibitively expensive. - example: 87 - TotalPages: - type: integer - format: int32 - minimum: 0 - maximum: 2147483647 - description: Total number of pages. Equals ceil(totalCount / perPage). MAY be omitted where totalCount is omitted. - example: 5 - responses: - ####################################################### - ####################################################### - # ERROR RESPONSE SCHEMA TEMPLATE - # - Objective: Make normative error `status` and `code` values - # - Schema Template rationale: - # - The `allOf` in content.application/json.schema allows a combination of both the generic ErrorInfo schema and the specific schema for this error response, - # which validates that `status` and `code` have only the specified values. - # This `allOf` is used without discriminator because it does not imply any hierarchy between the models, just 2 schemas that must be independently validated. - ####################################################### - # ErrorResponseSchema: - # ... - # content: - # application/json: - # schema: - # allOf: - # - $ref: '#/components/schemas/ErrorInfo' - # - type: object - # properties: - # status: - # enum: - # - - # code: - # enum: - # - - # - - # examples: - # ExampleKey1: - # value: - # status: - # code: - # message: - # ExampleKey2: - # value: - # status: - # code: - # message: - ####################################################### - ####################################################### - Generic400: - description: Bad Request - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - INVALID_ARGUMENT - - OUT_OF_RANGE - # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed - 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_{{SPECIFIC_CODE}}: - # description: Specific Syntax Exception regarding a field that is relevant in the context of the API - # value: - # status: 400 - # code: "{{SPECIFIC_CODE}}" - # message: Message for specific code - Generic401: - description: Unauthorized - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 401 - code: - enum: - - UNAUTHENTICATED - examples: - GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated and a new authentication is required - value: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. - Generic403: - description: Forbidden - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 403 - code: - enum: - - PERMISSION_DENIED - - INVALID_TOKEN_CONTEXT - # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed - 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." - message: "Request body is not consistent with access token." - # GENERIC_403_{{SPECIFIC_CODE}}: - # description: Indicate a Business Logic condition that forbids a process not attached to a specific field in the context of the API - # value: - # status: 403 - # code: "{{SPECIFIC_CODE}}" - # message: Message for specific code - Generic404: - description: Not found - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 404 - code: - enum: - - NOT_FOUND - - IDENTIFIER_NOT_FOUND - # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed - 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_IDENTIFIER_NOT_FOUND: - description: Some identifier cannot be matched to a device - value: - status: 404 - code: IDENTIFIER_NOT_FOUND - message: Device identifier not found. - # GENERIC_404_{{SPECIFIC_CODE}}: - # description: Specific situation to highlight the resource/concept not found - # value: - # status: 404 - # code: "{{SPECIFIC_CODE}}" - # message: Message for specific code - Generic405: - description: Method Not Allowed - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 405 - code: - enum: - - METHOD_NOT_ALLOWED - 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. - Generic406: - description: Not Acceptable - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 406 - code: - enum: - - NOT_ACCEPTABLE - examples: - GENERIC_406_NOT_ACCEPTABLE: - description: API Server does not accept the media type (`Accept-*` header) indicated by API client - value: - status: 406 - code: NOT_ACCEPTABLE - message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. - Generic409: - description: Conflict - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 409 - code: - enum: - - ABORTED - - ALREADY_EXISTS - - CONFLICT - - INCOMPATIBLE_STATE - # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed - examples: - GENERIC_409_ABORTED: - description: The resource is undergoing modification by another process - value: - status: 409 - code: ABORTED - message: Resource is being modified by another operation. Please wait, and retry if appropriate. - 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: - ################################### - # This Error Code is DEPRECATED - ################################### - description: Duplication of an existing resource - value: - status: 409 - code: CONFLICT - message: A specified resource duplicate entry found. - GENERIC_409_INCOMPATIBLE_STATE: - description: | - The status of the referenced resource is not compatible. - value: - status: 409 - code: INCOMPATIBLE_STATE - message: Resource must be in AVAILABLE state to extend. Current state is UNAVAILABLE. - # GENERIC_409_{{SPECIFIC_CODE}}: - # description: Specific conflict situation that is relevant in the context of the API - # value: - # status: 409 - # code: "{{SPECIFIC_CODE}}" - # message: Message for specific code - Generic410: - description: Gone - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 410 - code: - enum: - - GONE - 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. - Generic412: - description: Failed precondition - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 412 - code: - enum: - - FAILED_PRECONDITION - examples: - GENERIC_412_FAILED_PRECONDITION: - description: Indication by the API Server that the request cannot be processed in current system state - value: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. - Generic415: - description: Unsupported Media Type - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 415 - code: - enum: - - UNSUPPORTED_MEDIA_TYPE - 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" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 422 - code: - enum: - - SERVICE_NOT_APPLICABLE - - MISSING_IDENTIFIER - - UNSUPPORTED_IDENTIFIER - - UNNECESSARY_IDENTIFIER - # - "{{SPECIFIC_CODE}}" - API-specific codes added if needed - examples: - GENERIC_422_SERVICE_NOT_APPLICABLE: - description: Service not applicable for the provided identifier - value: - status: 422 - code: SERVICE_NOT_APPLICABLE - message: The service is not available for the provided identifier. - GENERIC_422_MISSING_IDENTIFIER: - description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token - value: - status: 422 - code: MISSING_IDENTIFIER - message: The device cannot be identified. - GENERIC_422_UNSUPPORTED_IDENTIFIER: - description: None of the provided identifiers is supported by the implementation - value: - status: 422 - code: UNSUPPORTED_IDENTIFIER - message: The identifier provided is not supported. - GENERIC_422_UNNECESSARY_IDENTIFIER: - description: An explicit identifier is provided when a device or phone number has already been identified from the access token - value: - status: 422 - code: UNNECESSARY_IDENTIFIER - message: The device is already identified by the access token. - # GENERIC_422_{{SPECIFIC_CODE}}: - # description: Any semantic condition associated to business logic, specifically related to a field or data structure - # value: - # status: 422 - # code: "{{SPECIFIC_CODE}}" - # message: Message for specific code - Generic429: - description: Too Many Requests - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 429 - code: - enum: - - QUOTA_EXCEEDED - - TOO_MANY_REQUESTS - examples: - GENERIC_429_QUOTA_EXCEEDED: - description: Request is rejected due to exceeding a business quota limit - value: - status: 429 - code: QUOTA_EXCEEDED - message: Out of resource quota. - GENERIC_429_TOO_MANY_REQUESTS: - description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached - value: - status: 429 - code: TOO_MANY_REQUESTS - message: Rate limit reached. - Generic500: - description: Internal Server Error - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 500 - code: - enum: - - INTERNAL - 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: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 501 - code: - enum: - - NOT_IMPLEMENTED - 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: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 502 - code: - enum: - - BAD_GATEWAY - 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" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 503 - code: - enum: - - 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. - Generic504: - description: Gateway Timeout - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 504 - code: - enum: - - TIMEOUT - examples: - GENERIC_504_TIMEOUT: - description: API Server Timeout - value: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. diff --git a/code/common/CAMARA_event_common.yaml b/code/common/CAMARA_event_common.yaml deleted file mode 100644 index 42e72db..0000000 --- a/code/common/CAMARA_event_common.yaml +++ /dev/null @@ -1,650 +0,0 @@ -info: - title: CAMARA common event and subscription data types - description: | - Common data types for CAMARA event notification and subscription management. - This file contains Commonalities-owned schemas that are identical across all - CAMARA APIs supporting event notifications and/or explicit subscriptions. - - API repositories place this file in `code/common/` alongside `CAMARA_common.yaml` - and reference schemas via `$ref: "../common/CAMARA_event_common.yaml#/components/schemas/"`. - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip - x-camara-commonalities: 0.8.0 - -components: - securitySchemes: - notificationsBearerAuth: - type: http - scheme: bearer - bearerFormat: "{$request.body#/sinkCredential.credentialType}" - description: | - Bearer token for notification delivery. Token format is determined - by `sinkCredential.credentialType` in the subscription request. - - schemas: - - # ───────────────────────────────────────────────────────────────────────── - # Section 1: CloudEvents 1.0 envelope - # - # Pure CloudEvents 1.0 specification envelope. Knows nothing about CAMARA - # event types, data payloads, or discriminator mappings. Any CAMARA API - # that needs to send a notification starts here. - # ───────────────────────────────────────────────────────────────────────── - - CloudEvent: - type: object - description: | - CloudEvents 1.0 specification envelope. - This schema is the stable base for all CAMARA event notifications. - It imposes no constraints on `type` values or `data` structure — - those concerns belong to the API-specific and lifecycle group schemas. - required: - - id - - source - - specversion - - type - - time - properties: - id: - type: string - maxLength: 256 - description: Identifier of this event, unique within the source context. - source: - $ref: "#/components/schemas/Source" - type: - type: string - maxLength: 512 - description: | - Identifies the event type. CAMARA APIs use reverse-DNS notation: - `org.camaraproject...` - The api-name segment makes each type globally unique across API groups. - 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: - type: object - description: Event details payload. Structure is defined by each concrete event schema. - time: - $ref: "CAMARA_common.yaml#/components/schemas/DateTime" - - Source: - type: string - format: uri-reference - minLength: 1 - maxLength: 2048 - description: | - Identifies the context in which an event happened - be 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.example.com" - - # ───────────────────────────────────────────────────────────────────────── - # Section 2: Subscription management - # - # Configuration and identification schemas used by the subscription - # management endpoints. These are Commonalities-owned and identical - # across all CAMARA APIs that support explicit subscriptions. - # ───────────────────────────────────────────────────────────────────────── - - SubscriptionId: - type: string - maxLength: 256 - description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, it SHALL be referred to as `subscriptionId` as per the Commonalities Event Notification Model. - example: qs15-h556-rt89-1298 - - 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 types, all subscribed events will use same `config` parameters. - type: object - required: - - subscriptionDetail - properties: - subscriptionDetail: - $ref: "#/components/schemas/CreateSubscriptionDetail" - subscriptionExpireTime: - type: string - format: date-time - maxLength: 64 - example: 2023-01-17T13:18:23.682Z - description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Up to API project decision to keep it. - subscriptionMaxEvents: - type: integer - format: int32 - 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 - maximum: 1000000 - 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. - - CreateSubscriptionDetail: - description: The detail of the requested event subscription. - type: object - - # ───────────────────────────────────────────────────────────────────────── - # Section 3: Protocol support - # - # Protocol selection and protocol-specific delivery settings. - # These are Commonalities-owned and identical across all CAMARA APIs. - # ───────────────────────────────────────────────────────────────────────── - - Protocol: - type: string - enum: - - HTTP - # Future protocol support (not yet used in CAMARA): - # - MQTT3 - # - MQTT5 - # - AMQP - # - NATS - # - KAFKA - description: Identifier of a delivery protocol. Only HTTP is allowed for now - example: "HTTP" - - HTTPSettings: - type: object - description: HTTP protocol settings for event delivery. - properties: - headers: - type: object - description: |- - A set of key/value pairs that is copied into the HTTP request as custom headers. - - NOTE: Use/Applicability of this concept has not been discussed in Commonalities. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it. - additionalProperties: - type: string - maxLength: 512 - method: - type: string - description: The HTTP method to use for sending the message. - enum: - - POST - - # Future protocol support (not yet used in CAMARA): - # MQTTSettings: - # type: object - # properties: - # topicName: - # type: string - # maxLength: 256 - # description: MQTT topic name - # qos: - # type: integer - # format: int32 - # minimum: 0 - # maximum: 2 - # description: Quality of Service level (0, 1, or 2) - # retain: - # type: boolean - # expiry: - # type: integer - # format: int32 - # minimum: 0 - # maximum: 2147483647 - # description: Message expiry interval in seconds - # userProperties: - # type: object - # required: - # - topicName - - # AMQPSettings: - # type: object - # properties: - # address: - # type: string - # maxLength: 512 - # linkName: - # type: string - # maxLength: 256 - # senderSettlementMode: - # type: string - # enum: ["settled", "unsettled"] - # linkProperties: - # type: object - # additionalProperties: - # type: string - # maxLength: 1024 - - # ApacheKafkaSettings: - # type: object - # properties: - # topicName: - # type: string - # maxLength: 249 - # partitionKeyExtractor: - # type: string - # maxLength: 512 - # clientId: - # type: string - # maxLength: 256 - # ackMode: - # type: integer - # format: int32 - # minimum: 0 - # maximum: 2 - # description: Acknowledgment mode (0=no ack, 1=leader ack, 2=all replicas ack) - # required: - # - topicName - - # NATSSettings: - # type: object - # properties: - # subject: - # type: string - # maxLength: 256 - # description: NATS subject - # required: - # - subject - - # ───────────────────────────────────────────────────────────────────────── - # Section 4: Sink credentials - # - # Authentication and authorization information for event delivery. - # These are Commonalities-owned and identical across all CAMARA APIs. - # ───────────────────────────────────────────────────────────────────────── - - SinkCredential: - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. - type: object - properties: - credentialType: - type: string - enum: - # - PLAIN # not used in CAMARA - - ACCESSTOKEN - - PRIVATE_KEY_JWT - description: | - The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now - discriminator: - propertyName: credentialType - mapping: - # PLAIN: "#/components/schemas/PlainCredential" # not used in CAMARA - ACCESSTOKEN: "#/components/schemas/AccessTokenCredential" - PRIVATE_KEY_JWT: "#/components/schemas/PrivateKeyJWTCredential" - required: - - credentialType - - # PlainCredential: # not used in CAMARA - # type: object - # description: A plain credential as a combination of an identifier and a secret. - # allOf: - # - $ref: "#/components/schemas/SinkCredential" - # - type: object - # required: - # - identifier - # - secret - # properties: - # identifier: - # description: The identifier might be an account or username. - # type: string - # maxLength: 256 - # secret: - # description: The secret might be a password or passphrase. - # type: string - # maxLength: 512 - - AccessTokenCredential: - type: object - description: An access token credential. This type of credential is meant to be used by API Consumers that have limited capabilities to handle authorization requests. - allOf: - - $ref: "#/components/schemas/SinkCredential" - - type: object - properties: - accessToken: - description: REQUIRED. An access token is a token granting access to the target resource. - type: string - maxLength: 4096 - writeOnly: true - accessTokenExpiresUtc: - type: string - format: date-time - maxLength: 64 - description: | - REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired. - In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date. - If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match. - It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - example: "2023-07-03T12:27:08.312Z" - accessTokenType: - description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). - type: string - writeOnly: true - enum: - - bearer - required: - - accessToken - - accessTokenExpiresUtc - - accessTokenType - - PrivateKeyJWTCredential: - type: object - description: Use PRIVATE_KEY_JWT to get an access token. This type of credential is to be used by clients that have an authorization server. - allOf: - - $ref: "#/components/schemas/SinkCredential" - - type: object - properties: - clientId: - description: The client ID used to authenticate when requesting an access token using PRIVATE_KEY_JWT. - type: string - maxLength: 128 - writeOnly: true - tokenUri: - description: The URI where to request an access token using PRIVATE_KEY_JWT. - type: string - format: uri - maxLength: 2048 - pattern: ^https:\/\/.+$ - writeOnly: true - jwksUri: - description: The URI used to request the public key to verify that the JWT assertion was signed by PRIVATE_KEY_JWT. - type: string - format: uri - maxLength: 2048 - pattern: ^https:\/\/.+$ - readOnly: true - - # ───────────────────────────────────────────────────────────────────────── - # Section 5: Subscription lifecycle data - # - # Data payload schemas for subscription lifecycle events. These define the - # `data` content of subscription-started, subscription-updated, and - # subscription-ended events. The lifecycle event wrappers (which contain - # api-name placeholders in their event type strings) stay in API templates. - # ───────────────────────────────────────────────────────────────────────── - - SubscriptionStarted: - description: Event detail structure for subscription started event - type: object - required: - - initiationReason - - subscriptionId - properties: - initiationReason: - $ref: "#/components/schemas/InitiationReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - initiationDescription: - type: string - maxLength: 512 - description: Description of subscription initiation - - InitiationReason: - type: string - description: | - - SUBSCRIPTION_CREATED - Subscription created by API Server - enum: - - SUBSCRIPTION_CREATED - - SubscriptionUpdated: - description: Event detail structure for subscription updated event - type: object - required: - - updateReason - - subscriptionId - properties: - updateReason: - $ref: "#/components/schemas/UpdateReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - updateDescription: - type: string - maxLength: 512 - description: Description of subscription update - - UpdateReason: - type: string - description: | - - SUBSCRIPTION_ACTIVE - API server transitioned subscription status to `ACTIVE` - - SUBSCRIPTION_INACTIVE - API server transitioned subscription status to `INACTIVE` - enum: - - SUBSCRIPTION_ACTIVE - - SUBSCRIPTION_INACTIVE - - SubscriptionEnded: - description: Event detail structure for subscription ended event - type: object - required: - - terminationReason - - subscriptionId - properties: - terminationReason: - $ref: "#/components/schemas/TerminationReason" - subscriptionId: - $ref: "#/components/schemas/SubscriptionId" - terminationDescription: - type: string - maxLength: 512 - description: Description of subscription termination - - 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 with credential type `ACCESSTOKEN`) expiration time has been reached - - SUBSCRIPTION_DELETED - Subscription was deleted by the requester - enum: - - MAX_EVENTS_REACHED - - NETWORK_TERMINATED - - SUBSCRIPTION_EXPIRED - - ACCESS_TOKEN_EXPIRED - - SUBSCRIPTION_DELETED - - # ───────────────────────────────────────────────────────────────────────── - # Subscription-specific error responses - # - # These extend generic CAMARA error codes with subscription-specific codes. - # Commonalities-owned and identical across all APIs using explicit subscriptions. - # ───────────────────────────────────────────────────────────────────────── - - responses: - CreateSubscriptionBadRequest400: - description: Problem with the client request - headers: - x-correlator: - $ref: "CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - INVALID_ARGUMENT - - OUT_OF_RANGE - - INVALID_PROTOCOL - - INVALID_CREDENTIAL - - INVALID_TOKEN - - INVALID_SINK - 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: - description: Invalid protocol for events subscription management - value: - status: 400 - code: INVALID_PROTOCOL - message: Only HTTP is supported - GENERIC_400_INVALID_CREDENTIAL: - description: Invalid sink credential type - value: - status: 400 - code: INVALID_CREDENTIAL - message: Only Access token or Private key JWT are supported - GENERIC_400_INVALID_SINK: - description: Invalid sink value - value: - status: 400 - code: INVALID_SINK - message: sink not valid for the specified protocol - - SubscriptionIdRequired400: - description: Problem with the client request - headers: - x-correlator: - $ref: "CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - 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_SUBSCRIPTION_ID_REQUIRED: - description: subscription id is required - value: - status: 400 - code: INVALID_ARGUMENT - message: "Expected property is missing: subscriptionId" - - SubscriptionPermissionDenied403: - description: Client does not have sufficient permission - headers: - x-correlator: - $ref: "CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 403 - code: - enum: - - PERMISSION_DENIED - - SUBSCRIPTION_MISMATCH - 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_SUBSCRIPTION_MISMATCH: - description: Inconsistent access token for requested subscription - value: - status: 403 - code: "SUBSCRIPTION_MISMATCH" - message: "Inconsistent access token for requested events subscription" - - CreateSubscriptionUnprocessableEntity422: - description: Unprocessable Entity - headers: - x-correlator: - $ref: "CAMARA_common.yaml#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "CAMARA_common.yaml#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 422 - code: - enum: - - SERVICE_NOT_APPLICABLE - - MISSING_IDENTIFIER - - UNSUPPORTED_IDENTIFIER - - UNNECESSARY_IDENTIFIER - - MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED - - MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED - - PRIVATE_KEY_JWT_NOT_CONFIGURED - examples: - GENERIC_422_SERVICE_NOT_APPLICABLE: - description: Service not applicable for the provided identifier - value: - status: 422 - code: SERVICE_NOT_APPLICABLE - message: The service is not available for the provided identifier. - GENERIC_422_MISSING_IDENTIFIER: - description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token - value: - status: 422 - code: MISSING_IDENTIFIER - message: The device cannot be identified. - GENERIC_422_UNSUPPORTED_IDENTIFIER: - description: None of the provided identifiers is supported by the implementation - value: - status: 422 - code: UNSUPPORTED_IDENTIFIER - message: The identifier provided is not supported. - GENERIC_422_UNNECESSARY_IDENTIFIER: - description: An explicit identifier is provided when a device or phone number has already been identified from the access token - value: - status: 422 - code: UNNECESSARY_IDENTIFIER - message: The device is already identified by the access token. - GENERIC_422_MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED: - description: Multi event types subscription is not supported - value: - status: 422 - code: MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED - message: Multi event types subscription not managed - GENERIC_422_MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED: - description: Combination of multiple event types is temporarily not supported - value: - status: 422 - code: MULTIEVENT_COMBINATION_TEMPORARILY_NOT_SUPPORTED - message: The requested combination of event types is temporarily not supported. - GENERIC_422_PRIVATE_KEY_JWT_NOT_CONFIGURED: - description: Private key JWT sink credential type is used but no configuration was pre-shared - value: - status: 422 - code: PRIVATE_KEY_JWT_NOT_CONFIGURED - message: No JWK Set configured for PRIVATE_KEY_JWT authentication. diff --git a/code/common/info-description-templates.yaml b/code/common/info-description-templates.yaml deleted file mode 100644 index 1c7928d..0000000 --- a/code/common/info-description-templates.yaml +++ /dev/null @@ -1,116 +0,0 @@ -# Mandatory `info.description` text templates for CAMARA API specs. -# -# This file is owned by Commonalities and synchronised into every onboarded -# CAMARA API repository as `code/common/info-description-templates.yaml` by the -# cache-common mechanism. Do not edit in API repositories. -# -# Each top-level key is a template name (lowercase-hyphenated, derived from -# the heading of its template). The `content` field holds the text that an -# API specification MUST embed as-is inside its `info.description`, bracketed -# by the BEGIN / END HTML-comment markers that are part of the content. -# -# Indentation is chosen so that copying the BEGIN..END region from this file -# into a target spec's `info.description` (`info:` column 0 -> `description: |` -# column 2 -> text column 4) preserves indentation with no fixup. -# -# Sources: -# - CAMARA API Design Guide (Commonalities) -# - CAMARA-API-access-and-user-consent.md (IdentityAndConsentManagement) -# If this file and a source document disagree, the source document wins; this -# file is regenerated to match. - -# Universal - mandatory in every CAMARA API. -# Source: -# IdentityAndConsentManagement/documentation/CAMARA-API-access-and-user-consent.md -# section "Mandatory template for `info.description` in CAMARA API specs" - -info: - x-camara-commonalities: 0.8.0 - -authorization-and-authentication: - content: | - - # Authorization and authentication - - The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. - - The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. - - In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. - - -# Universal - mandatory in every CAMARA API. -# Source: -# Commonalities/documentation/CAMARA-API-Design-Guide.md section 3.2.3 -# "Error Responses - Mandatory Template for `info.description` in CAMARA API" -additional-error-responses: - content: | - - # Additional CAMARA error responses - - The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. - - Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. - - As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. - - -# Universal - mandatory in every CAMARA API targeting Commonalities r4.3 or later. -# Source: -# Commonalities/documentation/CAMARA-API-Design-Guide.md section 3.2.4 -# "Request Body Strictness - Mandatory Template for `info.description` in CAMARA API" -request-body-strictness: - content: | - - # Request body strictness - - This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. - - -# Opt-in - applicable to APIs where the subject of an operation can be -# identified either implicitly from a three-legged access token or explicitly -# from a `device` object. Mutually exclusive with `identifying-phone-number-from-access-token`. -# Source: -# Commonalities/documentation/CAMARA-API-Design-Guide.md Appendix A, -# filled in with the `device` / `device` object choice. -identifying-device-from-access-token: - content: | - - # Identifying the device from the access token - - This API requires the API consumer to identify a device as the subject of the API as follows: - - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided. - - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. - - This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - - ## Error handling: - - - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - - - If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison. - - -# Opt-in - applicable to APIs where the subject of an operation can be -# identified either implicitly from a three-legged access token or explicitly -# from a `phoneNumber` field. Mutually exclusive with `identifying-device-from-access-token`. -# Source: -# Commonalities/documentation/CAMARA-API-Design-Guide.md Appendix A, -# filled in with the `phone number` / `phoneNumber` field choice. -identifying-phone-number-from-access-token: - content: | - - # Identifying the phone number from the access token - - This API requires the API consumer to identify a phone number as the subject of the API as follows: - - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. - - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. - - This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - - ## Error handling: - - - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - - - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. - diff --git a/release-metadata.yaml b/release-metadata.yaml new file mode 100644 index 0000000..832f9af --- /dev/null +++ b/release-metadata.yaml @@ -0,0 +1,13 @@ +repository: + repository_name: EdgeApplicationManagement + release_tag: r1.2 + release_type: pre-release-rc + release_date: null + src_commit_sha: eba92a2c83f00284e3cf209321f0939d1142f35a +apis: +- api_name: edge-application-management + api_version: 0.1.0-rc.1 + api_title: Edge Application Management +dependencies: + commonalities_release: r4.3 (0.8.0) + identity_consent_management_release: r4.2 (0.5.0) diff --git a/release-plan.yaml b/release-plan.yaml deleted file mode 100644 index a9b4ea2..0000000 --- a/release-plan.yaml +++ /dev/null @@ -1,42 +0,0 @@ -# CAMARA Release Plan -# This file declares release intentions for this repository. -# It replaces manual wiki tracking with automated tooling. -# -# Update this file; CI validates it; releases are generated from this plan. -# Docs: https://github.com/camaraproject/ReleaseManagement/tree/main/documentation - -repository: - # How this repository participates in CAMARA releases - # Options: independent (default) | meta-release - release_track: independent - - # Uncomment and set when planning a meta-release participation: - # meta_release: Sync26 - - # Release tag -- first release for a repository is r1.1 - # - New release cycle (increment first number, reset second to 1) - # - Progression in same cycle (increment second number) - target_release_tag: r1.2 - - # Release type being prepared (must be set before release can be triggered) - # Options: none | pre-release-alpha | pre-release-rc | public-release | maintenance-release - target_release_type: pre-release-rc - -# Dependencies on Commonalities and ICM releases -# Update per ReleaseManagement requirements for each release cycle -dependencies: - commonalities_release: r4.3 - identity_consent_management_release: r4.2 - -# APIs in this repository -# Replace the placeholder below when planning a release: -# - api_name: kebab-case identifier (used as filename in code/API_definitions/) -# - target_api_status: draft | alpha | rc | public (draft allows no file yet) -apis: - - api_name: edge-application-management - target_api_version: 0.1.0 - target_api_status: rc - main_contacts: - - JoseMConde - - Seralogar - - Kevsy