From 05ffc4ecd85dd9a65ec5b1fa971fc0321ccd0776 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Fri, 17 May 2024 01:43:54 +0200 Subject: [PATCH 01/25] Update API-design-guidelines.md update of version section step 1 --- documentation/API-design-guidelines.md | 62 +++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7644f5ec..e730b0a1 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -537,19 +537,67 @@ These considerations are below: ## 5. Versioning -### 5.1 Versioning Strategy +Versioning is a practice by which, when a change occurs in the API, a new version of that API is released so that the new version and the previous one coexists for a certain period of time. -Service versioning is a practice by which, when a change occurs in the API of a service, a new version of that service is released so that the new version and the previous one coexists for a certain period of time. +API versions use a numbering scheme in the format x.y.z, where x, y and z are numbers corresponding to MAJOR, MINOR and PATCH versions. MAJOR, MINOR and PATCH refer to the types of changes made to an API through its evolution. Depending on the change type, the corresponding number is incremented. This is defined in the [Semantic Versioning 2.0.0 (semver.org)](https://semver.org/) standard. -Consumers will be migrated to the new version of the service sequentially. When everyone is consuming the latest version of the service, the previous version is removed. +### 5.1 API version -Consumers can distinguish between one version of the service and another, the technique of adding the API version to the context of the base URL will be used, since this technique is the most used in the main reference APIs. +The API version is defined in the "version" field (in the Info object) of the OAS definition file of an API.  -The structure of the URL would have the following form: -```http -https://host:port/api/v1/resource + +```yaml +info: + title: Number Verification + description: text describing the API + version: 2.2.0   + ... +``` + +In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows: + +1. The MAJOR version when an incompatible / breaking API change is introduced +2. The MINOR version when functionality is added that is backwards compatible +3. The PATCH version when backward compatible bugs are fixed + +For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see (API versioning)(https://wiki.camaraproject.org/x/a4BaAQ).  + +It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be compatible with previous versions. + +More information on how to avoid breaking changes can be found here: API versioning - Breaking and non-breaking changes + +### 5.2 API version in URL + +The OAS file also defines the API version used in the URL of the API endpoint (in the servers object). + +The API endpoint URL only includes the "x" (MAJOR version) number of the API version as follows: + +```yaml +servers: +    url: {apiRoot}/qod/v2 ``` +NOTE: CAMARA exceptionally allows initial API versions (x=0) to have both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in the API version in the URL to allow for test and usage of initial API versions as they are evolving rapidly, e.g. /qod/v0.10, or /qod/v0.11alpha1. However, it should be acknowledged that any initial API version may change. + +### 5.3 API versions throughout the release process + +In preparation for its public-release, an API will go through various intermediate versions indicated by version extensions: alpha and release-candidate. + +Overall, an API can have any of the following versions: + +* work-in-progress (wip) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. +* alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes +* release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug fixing purposes +* public-release (x.y.z) API versions for publication as part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no extension. The public-release API can have one of two maturity states:  + * initial - indicating that the API is still not fully stable (x=0) + * stable - indicate that the API has reached a certain level of maturity (x>0) + +The following table gives the values of the API version (Info object) and the API version in the URL used in the release process of the API, and dependent on whether it is an initial API version (x=0) or a stable API version (x>0). + + + + + When we version through the URL, only the "MAJOR version" is included since this would change when a change incompatible with the previous version occurs. From 02b78ef6e88201f83073199af6bdb12713b85d71 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Fri, 17 May 2024 03:31:29 +0200 Subject: [PATCH 02/25] Update API-design-guidelines.md section 5. Version - update 3 update of TOC --- documentation/API-design-guidelines.md | 134 ++++++++++++++++++------- 1 file changed, 95 insertions(+), 39 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7644f5ec..7973ef48 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -27,8 +27,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [4.1 URL Definition](#41-url-definition) - [4.2 Input/Output Resource Definition](#42-inputoutput-resource-definition) - [5. Versioning](#5-versioning) - - [5.1 Versioning Strategy](#51-versioning-strategy) - - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) + - [5.1 API version (OAS Info object)](#51-api-version-oas-info-object) + - [5.2 API version in URL (OAS servers object)](#52-api-version-in-url-oas-servers-object) + - [5.3 API versions throughout the release process](#53-api-versions-throughout-the-release-process) + - [5.4 Backwards and Forward Compatibility](#54-backwards-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) @@ -537,45 +539,89 @@ These considerations are below: ## 5. Versioning -### 5.1 Versioning Strategy +Versioning is a practice by which, when a change occurs in the API, a new version of that API is released so that the new version and the previous one coexists for a certain period of time. -Service versioning is a practice by which, when a change occurs in the API of a service, a new version of that service is released so that the new version and the previous one coexists for a certain period of time. +API versions use a numbering scheme in the format: x.y.z -Consumers will be migrated to the new version of the service sequentially. When everyone is consuming the latest version of the service, the previous version is removed. +* x, y and z are numbers corresponding to MAJOR, MINOR and PATCH versions. +* MAJOR, MINOR and PATCH refer to the types of changes made to an API through its evolution. +* Depending on the change type, the corresponding number is incremented. +* This is defined in the [Semantic Versioning 2.0.0 (semver.org)](https://semver.org/) standard. -Consumers can distinguish between one version of the service and another, the technique of adding the API version to the context of the base URL will be used, since this technique is the most used in the main reference APIs. +### 5.1 API version (OAS Info object) -The structure of the URL would have the following form: -```http -https://host:port/api/v1/resource +The API version is defined in the "version" field (in the Info object) of the OAS definition file of an API.  + +```yaml +info: + title: Number Verification + description: text describing the API + version: 2.2.0   + ... +``` + +In the URL, only the "MAJOR version" is included since this number would change when a change incompatible with the previous version occurs. + +In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows: + +1. The MAJOR version when an incompatible / breaking API change is introduced +2. The MINOR version when functionality is added that is backwards compatible +3. The PATCH version when backward compatible bugs are fixed + +For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ).  + +It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. + +More information on how to avoid breaking changes can be found below. + +### 5.2 API version in URL (OAS servers object) + +The OAS file also defines the API version used in the URL of the API endpoint (in the servers object). + +The API endpoint URL only includes the "x" (MAJOR version) number of the API version as follows: + +```yaml +servers: +    url: {apiRoot}/qod/v2 ``` +NOTE: CAMARA exceptionally allows initial API versions (x=0) to have both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in the API version in the URL. + +This allows for test and usage of initial API versions as they are evolving rapidly, e.g. /qod/v0.10, or /qod/v0.11alpha1. However, it should be acknowledged that any initial API version may change. -When we version through the URL, only the "MAJOR version" is included since this would change when a change incompatible with the previous version occurs. +### 5.3 API versions throughout the release process -API implementation versioning will follow semantic versioning. Given a `MAJOR.MINOR.PATCH` version number, it increments: -1) The `MAJOR` version when you make an incompatible API change. -2) The `MINOR` version when you add functionality that is backwards compatible. -3) The `PATCH` version when you fix backward compatible bugs. +In preparation for its public-release, an API will go through various intermediate versions indicated by version extensions: alpha and release-candidate. -Related to the versioning of rest parts involved in Apification projects, best practises are detailed below: +Overall, an API can have any of the following versions: -SHARED CODE ON REPOSITORIES +* work-in-progress (wip) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. +* alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes +* release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug fixing purposes +* public-release (x.y.z) API versions for publication as part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no extension. The public-release API can have one of two maturity states:  + * initial - indicating that the API is still not fully stable (x=0) + * stable - indicate that the API has reached a certain level of maturity (x>0) -1) MAJOR - Major of API Contract -2) MINOR - Minor of API Contract -3) PATCH - New Updates / Contributions of shared code +The following table gives the values of the API version (Info object) and the API version in the URL used in the release process of the API, and dependent on whether it is an initial API version (x=0) or a stable API version (x>0). -MICROSERVICE DEPLOYMENTS (NOT MANDATORY BUT RECOMMENDED) +| API version in  release process | API version | initial (x=0) API version in URL | stable (x>0) API version in URL | API version can be released | +|---------------|:------:|:------:|:------:|:------:| +| work-in-progress | wip | vwip | vwip | No | +| alpha | x.y.z-alpha.m | v0.yalpham | vxalpham |Yes (internal) | +| release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal) | +| public-release | x.y.z | v0.y | vx | Yes | -1) MAJOR - Major of API Contract -2) MINOR - Minor of API Contract -3) PATCH - New Microservice Deployments +Precedence examples: +* 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0. +* 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public-release) +* 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (stable public-release) -### 5.2 Backwards and Forward Compatibility +For more information, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management project Wiki. -Avoid breaking backwards compatibility unless strictly necessary, that means, new versions should be compatible with previous versions. +### 5.4 Backwards and Forward Compatibility + +Avoid breaking backwards compatibility, unless strictly necessary, means that new versions should be compatible with previous versions. Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account: @@ -585,30 +631,36 @@ Bearing in mind that APIs are continually evolving and certain operations will n - Remove deprecated APIs documentation. - Never start using already deprecated APIs. + Types of modification: - Types of modification +- Not all API changes have an impact on API consumers. Such changes are referred to as backward compatible changes. +- If the API undergoes changes of this type, it shall be provided through a maintenance-release which will replace the current one. +- Consumers shall be notified of the new release so that they take them into account. -Not all API changes have an impact on API consumers. These changes are often referred to as backward compatible changes. If the API undergoes changes of this type, it should not be necessary to release a new version, it will suffice to replace the current one. What would be very convenient is to notify our consumers with the new changes so that they take them into account. +Backward compatible changes to an API that **DO NOT** affect consumers: -This is a list of changes to an API that **DO NOT** affect consumers: +- Adding a new endpoint +- Adding new operations on a resource (`PUT`, `POST`, ...). +- Adding optional input parameters to requests on existing resources. For example, adding a new filter parameter in a GET on a collection of resources. +- Changing an input parameter from reqmandatory to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. +- Adding new properties in the representation of a resource returned by the server. For example, adding a new age field to a Person resource, which originally was made up of nationality and name. -- Add new operations to the service. Translated to REST, it would be to add new actions on a resource (`PUT`, `POST`, ...). -- Add optional input parameters to requests on existing resources. For example, adding a new filter parameter in a GET on a collection of resources. -- Modify input parameters from required to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. -- Add new properties in the representation of a resource returned by the server. For example, adding a new age field to a Person resource, which originally was made up of nationality and name. +Breaking changes to an API that **DO** affect consumers: -This other list shows changes that **DO** affect consumers: -- Delete operations or actions on a resource. For example: POST requests on a resource are no longer accepted. -- Add new mandatory input parameters. For example: now, to register a resource, a new required field must be sent in the body of the request. -- Modify input parameters from optional to mandatory. For example: when creating a Person resource, the age field, which was previously optional, is now mandatory. -- Modify a parameter in existing operations (resource verbs). Also applicable to parameter removal. For example, when consulting a resource, a certain field is no longer returned. Another example: a field that was previously a string is now numeric. -- Add new responses to existing operations. For example: creating a resource can return a 412 response code. +- Deleting operations or actions on a resource. For example: POST requests on a resource are no longer accepted. +- Adding new mandatory input parameters. For example: now, to register a resource, a new required field must be sent in the body of the request. +- Modifying or removing an endpoint (breaks existing queries) +- Changing input parameters from optional to mandatory. For example: when creating a Person resource, the age field, which was previously optional, is now mandatory. +- Modifying or removing a mandatory parameter in existing operations (resource verbs). For example, when consulting a resource, a certain field is no longer returned. Another example: a field that was previously a string is now numeric. +- Modifying or adding new responses to existing operations. For example: creating a resource can return a 412 response code. Compatibility management Tho ensure this compatibility, the following must be followed. -**As API producer**: +**As API provider**: +- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a minor release and remove it in a later major release (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality) +- If possible, do the same for attributes - New fields should always be added as optional. - Postel's Law: “Be conservative in what you do, be liberal in what you accept from others”. When you have input fields that need to be removed, mark them as unused, so they can be ignored. - Do not change the field’s semantics. @@ -617,6 +669,10 @@ Tho ensure this compatibility, the following must be followed. - If you use collections that can be returned with no content, then answer with an empty collection and not null. - Layout pagination support from the start. +Make the information available: +- provide an access to the new API version definition file (via a link or dedicated endpoint) +- if possible, do the same to obtain the currently implemented API version definition file + **As API consumer**: - Tolerant reader: if it does not recognize a field when faced with a response from a service, do not process it, but record it through the log (or resend it if applicable). - Ignore fields with null values. From ed7035c14854e31769ee2b38584c19322f4d3bef Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Tue, 21 May 2024 01:57:46 +0200 Subject: [PATCH 03/25] Update API-design-guidelines.md final adjustments --- documentation/API-design-guidelines.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7973ef48..97b83c13 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -560,8 +560,6 @@ info: ... ``` -In the URL, only the "MAJOR version" is included since this number would change when a change incompatible with the previous version occurs. - In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows: 1. The MAJOR version when an incompatible / breaking API change is introduced @@ -570,15 +568,13 @@ In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH versio For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ).  -It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. - -More information on how to avoid breaking changes can be found below. +It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. ### 5.2 API version in URL (OAS servers object) The OAS file also defines the API version used in the URL of the API endpoint (in the servers object). -The API endpoint URL only includes the "x" (MAJOR version) number of the API version as follows: +The API version in the URL only includes the "x" (MAJOR version) number of the API version as follows: ```yaml servers: From 142c5f6156c68497fe3ac1d12a2a7e2e67a24974 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Fri, 24 May 2024 18:58:51 +0200 Subject: [PATCH 04/25] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 97b83c13..e87041ef 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -566,7 +566,7 @@ In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH versio 2. The MINOR version when functionality is added that is backwards compatible 3. The PATCH version when backward compatible bugs are fixed -For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ).  +For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [versioning in the API release process](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management wiki.  It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. @@ -581,7 +581,7 @@ servers:     url: {apiRoot}/qod/v2 ``` -NOTE: CAMARA exceptionally allows initial API versions (x=0) to have both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in the API version in the URL. +NOTE: CAMARA exceptionally allows to use both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in initial API versions (x=0) in the API version in the URL. This allows for test and usage of initial API versions as they are evolving rapidly, e.g. /qod/v0.10, or /qod/v0.11alpha1. However, it should be acknowledged that any initial API version may change. From a07b55d744073c45e59fc6e3058c71e13b3ad83e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 14:34:45 +0200 Subject: [PATCH 05/25] Proposal to simplify device object and improve interoperability --- artifacts/CAMARA_common.yaml | 8 ----- documentation/API-design-guidelines.md | 43 +++++++++++++++++++++++++- 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index be3c4b6b..c9c51423 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -59,14 +59,11 @@ components: * `ipv4Address` * `ipv6Address` * `phoneNumber` - * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. type: object properties: phoneNumber: $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: @@ -79,11 +76,6 @@ components: pattern: '^\+[1-9][0-9]{4,14}$' 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 - example: "123456789@domain.com" - DeviceIpv4Addr: type: object description: | diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 1c825041..02ca085b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -50,7 +50,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) - [11.6.1 Scope naming](#1161-scope-naming) - - [Examples](#examples) + - [Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are:](#regarding-scope-naming-for-apis-which-do-not-deal-with-explicit-subscriptions-the-guidelines-are) + - [Examples](#examples) + - [Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below:](#regarding-scope-naming-for-apis-which-deal-with-explicit-subscriptions-the-guidelines-propose-some-changes-as-compared-to-the-above-format-and-this-is-described-below) + - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) - [12. Subscription, Notification \& Event](#12-subscription-notification--event) - [12.1 Subscription](#121-subscription) - [Instance-based (implicit) subscription](#instance-based-implicit-subscription) @@ -66,6 +69,7 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Security Considerations](#security-considerations) - [Abuse Protection](#abuse-protection) - [Notification examples](#notification-examples) + - [Appendix A: `info.description` template for `device` identification from access token](#appendix-a-infodescription-template-for-device-identification-from-access-token) ## Common Vocabulary and Acronyms @@ -1704,3 +1708,40 @@ response: ```http 204 No Content ``` + +## Appendix A: `info.description` template for `device` identification from access token + +The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. + + +```md +# Identifying a user device from the access token + +This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. This mechanism reduces the need for multiple identifiers and extensive validation. + +## Handling of device information: + +### Optional device object for 3-legged tokens: + +- When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + +### Validation mechanism: + +- The server will extract the device identification from the access token, if available. +- If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. +- If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token. + +### Error handling for unidentifiable devices: + +- If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. + +### Restrictions for tokens without an associated authenticated identifier: + +- For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + +By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. +``` + +Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a user device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. + +Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make `device` object more interoperable and usable for API consumers. From c0dfc8a79078d5f3881eaf6e8c5fbc7631663017 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 16:51:51 +0200 Subject: [PATCH 06/25] Fixed indentation in table of contents --- documentation/API-design-guidelines.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 02ca085b..caf0f895 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -50,10 +50,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) - [11.6.1 Scope naming](#1161-scope-naming) - - [Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are:](#regarding-scope-naming-for-apis-which-do-not-deal-with-explicit-subscriptions-the-guidelines-are) + - [APIs which do not deal with explicit subscriptions](#apis-which-do-not-deal-with-explicit-subscriptions) - [Examples](#examples) - - [Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below:](#regarding-scope-naming-for-apis-which-deal-with-explicit-subscriptions-the-guidelines-propose-some-changes-as-compared-to-the-above-format-and-this-is-described-below) - - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) + - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions) + - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) - [12. Subscription, Notification \& Event](#12-subscription-notification--event) - [12.1 Subscription](#121-subscription) - [Instance-based (implicit) subscription](#instance-based-implicit-subscription) @@ -1280,7 +1280,9 @@ The [CAMARA API Specification - Authorization and authentication common guidelin #### 11.6.1 Scope naming -#### Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are: +##### APIs which do not deal with explicit subscriptions + +Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are: * Define a scope per API operation with the structure: @@ -1303,6 +1305,7 @@ where - `write` : For operations creating or modifying the resource, when differentiation between `create` and `update` is not needed. * Eventually we may need to add an additional level to the scope, such as `api-name:[resource:]action[:detail]`, to deal with cases when only a set of parameters/information has to be allowed to be returned. Guidelines should be enhanced when those cases happen. + ###### Examples | API | path | method | scope | @@ -1313,8 +1316,9 @@ where
+##### APIs which deal with explicit subscriptions -#### Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below: +Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below: Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: @@ -1329,7 +1333,8 @@ Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on Grant-level, action on resource: create For e.g. device-roaming-subscriptions:org.camaraproject.device-roaming-subscriptions.v0.roaming-on:create -#### API-level scopes (sometimes referred to as wildcard scopes in CAMARA) +##### API-level scopes (sometimes referred to as wildcard scopes in CAMARA) + The decision on the API-level scopes was made within the [Identity and Consent Management Working Group](https://github.com/camaraproject/IdentityAndConsentManagement) and is documented in the design guidelines to ensure completeness of this document. The scopes will always be those defined in the API Specs YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API Spec YAML file and agreed in the corresponding API subproject. From b7f7c76407dfebdfd859cab56576770d8f9c4981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 17:14:55 +0200 Subject: [PATCH 07/25] Improved descriptions --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index caf0f895..7db7ce93 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1742,7 +1742,7 @@ This specification defines the `device` object field as optional in API requests ### Restrictions for tokens without an associated authenticated identifier: -- For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. +- For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. ``` From 8e2c4e612e05844e2b58eb61a84ef192efaea244 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Tue, 11 Jun 2024 17:22:12 +0200 Subject: [PATCH 08/25] Update documentation/API-design-guidelines.md Co-authored-by: Herbert Damker <52109189+hdamker@users.noreply.github.com> --- documentation/API-design-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index e87041ef..b2d826d7 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -603,8 +603,8 @@ The following table gives the values of the API version (Info object) and the AP | API version in  release process | API version | initial (x=0) API version in URL | stable (x>0) API version in URL | API version can be released | |---------------|:------:|:------:|:------:|:------:| | work-in-progress | wip | vwip | vwip | No | -| alpha | x.y.z-alpha.m | v0.yalpham | vxalpham |Yes (internal) | -| release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal) | +| alpha | x.y.z-alpha.m | v0.yalpham | vxalpham |Yes (internal pre-release) | +| release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal pre-release) | | public-release | x.y.z | v0.y | vx | Yes | Precedence examples: From 633bc14be5a588906d9e28123fc8ac302a8fdf36 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Tue, 11 Jun 2024 23:03:17 +0200 Subject: [PATCH 09/25] Update API-design-guidelines.md Update following comments on backward compatibility section --- documentation/API-design-guidelines.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index b2d826d7..b430ec9a 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -539,7 +539,7 @@ These considerations are below: ## 5. Versioning -Versioning is a practice by which, when a change occurs in the API, a new version of that API is released so that the new version and the previous one coexists for a certain period of time. +Versioning is a practice by which, when a change occurs in the API, a new version of that API is released. The new version and the previous one may coexist for a certain period of time. API versions use a numbering scheme in the format: x.y.z @@ -629,9 +629,10 @@ Bearing in mind that APIs are continually evolving and certain operations will n Types of modification: -- Not all API changes have an impact on API consumers. Such changes are referred to as backward compatible changes. -- If the API undergoes changes of this type, it shall be provided through a maintenance-release which will replace the current one. -- Consumers shall be notified of the new release so that they take them into account. +- Not all API changes have an impact on API consumers. These are referred to as backward compatible changes. +- In case of such changes, the update produces a new API version that increases the MINOR or PATCH version number. +- The update can be deployed transparently as it does not change the endpoint of the API which only contains the MAJOR version number which has not changed, and all previously existing behaviour shall be the same. +- API consumers shall be notified of the new version availability so that they can take it into account. Backward compatible changes to an API that **DO NOT** affect consumers: From f1ef81235f22ce51e12043e900c1fa7c7d397d69 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Wed, 12 Jun 2024 17:25:38 +0200 Subject: [PATCH 10/25] Update API-design-guidelines.md - removing release aspects Changed the use of "public-release" to just "public" Removed references to release aspects for the versioning section --- documentation/API-design-guidelines.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index b430ec9a..f84501e4 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -539,7 +539,7 @@ These considerations are below: ## 5. Versioning -Versioning is a practice by which, when a change occurs in the API, a new version of that API is released. The new version and the previous one may coexist for a certain period of time. +Versioning is a practice by which, when a change occurs in the API, a new version of that API is created. API versions use a numbering scheme in the format: x.y.z @@ -566,7 +566,7 @@ In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH versio 2. The MINOR version when functionality is added that is backwards compatible 3. The PATCH version when backward compatible bugs are fixed -For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [versioning in the API release process](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management wiki.  +For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the CAMARA wiki.  It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. @@ -587,31 +587,31 @@ This allows for test and usage of initial API versions as they are evolving rapi ### 5.3 API versions throughout the release process -In preparation for its public-release, an API will go through various intermediate versions indicated by version extensions: alpha and release-candidate. +In preparation for its public release, an API will go through various intermediate versions indicated by version extensions: alpha and release-candidate. Overall, an API can have any of the following versions: * work-in-progress (wip) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. * alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes * release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug fixing purposes -* public-release (x.y.z) API versions for publication as part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no extension. The public-release API can have one of two maturity states:  +* public (x.y.z) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states:  * initial - indicating that the API is still not fully stable (x=0) * stable - indicate that the API has reached a certain level of maturity (x>0) -The following table gives the values of the API version (Info object) and the API version in the URL used in the release process of the API, and dependent on whether it is an initial API version (x=0) or a stable API version (x>0). +The following table gives the values of the API version (Info object) and the API version in the URL as used in the different API version types created during the API release process. For public API versions, this information is also dependent on whether it is an initial (x=0) or a stable public API version (x>0). -| API version in  release process | API version | initial (x=0) API version in URL | stable (x>0) API version in URL | API version can be released | +| API version type | API version | initial (x=0) API version in URL | stable (x>0) API version in URL | API version can be released | |---------------|:------:|:------:|:------:|:------:| | work-in-progress | wip | vwip | vwip | No | | alpha | x.y.z-alpha.m | v0.yalpham | vxalpham |Yes (internal pre-release) | | release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal pre-release) | -| public-release | x.y.z | v0.y | vx | Yes | +| public | x.y.z | v0.y | vx | Yes | Precedence examples: * 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0. -* 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public-release) -* 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (stable public-release) +* 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public API version) +* 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (stable public API version) For more information, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management project Wiki. @@ -621,7 +621,7 @@ Avoid breaking backwards compatibility, unless strictly necessary, means that ne Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account: -- Agree to discontinue an API with consumers. +- Agree to discontinue an API version with consumers. - Establish the obsolescence of the API in a reasonable period (6 months). - Monitor the use of deprecated APIs. - Remove deprecated APIs documentation. From 50bc2f7fad267bacd02049a928ea9670c91b1472 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Wed, 12 Jun 2024 18:08:52 +0200 Subject: [PATCH 11/25] Delete documentation/Camara_Versioning_Guidelines.md release mgmt information is moved to the Release Mgmt repo --- documentation/Camara_Versioning_Guidelines.md | 28 ------------------- 1 file changed, 28 deletions(-) delete mode 100644 documentation/Camara_Versioning_Guidelines.md diff --git a/documentation/Camara_Versioning_Guidelines.md b/documentation/Camara_Versioning_Guidelines.md deleted file mode 100644 index c4c66111..00000000 --- a/documentation/Camara_Versioning_Guidelines.md +++ /dev/null @@ -1,28 +0,0 @@ -# Camara subproject release guidelines - -* Release name for subprojects should be same as the tag-name for e.g. v0.8.0. The GitHub [release feature](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) should be used for this purpose. If referenced outside the subproject, it can be referred to as Release **\\** for e.g. Release QualityOnDemand v0.8.0 -* Every release includes the **CHANGELOG.md** file in the root directory of the subproject. Please make sure that the content is structured in a format that is easy to read. Please refer to the template provided here for possible sections that could be added to a changelog [CHANGELOG_TEMPLATE.md](./SupportingDocuments/CHANGELOG_TEMPLATE.md). Every release would add to the changelog. An example of how a changelog could look over time is shown below. -* The release can be agreed within the subproject by making a pull request for the changelog. The merge of this pull request would be marked as the release commit and the text within the changelog would be used as the release description -* Changelog content: - * APIs/Software in alpha release needs to be clearly specified - * API changes (This should include/cover all API objects which are part of the API bundle) - * New features - * Fixes - * Deprecation (if any) -* Going ahead, we could decide on a pull request process where use of right PR annotations could allow us to use tooling such as [krel](https://github.com/kubernetes/release/blob/master/docs/krel/README.md) or similar to automate at least parts of release management. -* Release branches should have naming convention **release-x.y.z** -* Release tags should follow the naming conventions vx.y.z for versions -* Adding relevant annotations to tags will be useful for later reference. -* Provider implementation repos can have their own naming conventions with regard to branches, tags etc. It is however mandatory to provide as a part of the  CHANGELOG.md - the API release version, capabilities and changes that are a part of the respective provider implementation release. -* Main branch is assumed to be the latest. -* Camara subproject will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release of any given subproject within Camara. -* The commonalities WG does not impose any restrictions on the subprojects for creating other branches, tags which might be needed/useful to address their specific requirements. The above said guidelines are only applicable for the subproject releases. -* Main (`main`) branch and all release branches (`release\*`) will be protected by branch rules in GitHub: All pull requests need to be reviewed by at least one code owner before they can be merged - -### Release branches -Ver - -### Changelog -Changelog From b817b7db54c39db34197c4a72360f869c8174e3a Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Wed, 12 Jun 2024 19:26:44 +0200 Subject: [PATCH 12/25] Update API-design-guidelines.md complement to removing release info from versioning section --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index f84501e4..d770181a 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -656,7 +656,7 @@ Breaking changes to an API that **DO** affect consumers: Tho ensure this compatibility, the following must be followed. **As API provider**: -- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a minor release and remove it in a later major release (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality) +- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later MAJOR change (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality) - If possible, do the same for attributes - New fields should always be added as optional. - Postel's Law: “Be conservative in what you do, be liberal in what you accept from others”. When you have input fields that need to be removed, mark them as unused, so they can be ignored. From 528f32007a9866a0b1780012092bbf190548a7e9 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Wed, 12 Jun 2024 19:32:07 +0200 Subject: [PATCH 13/25] Update README.md removed the references to 2 removed documents and added note to point to ReleaseManagement repo --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 062ac16e..2ae79289 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,11 @@ A list of some of the frequently accessed documents that are an output of the wo |-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [API-design-guidelines.md](documentation/API-design-guidelines.md) | This document captures guidelines for the API design in CAMARA project. These guidelines are applicable to every API to be worked out under the CAMARA initiative. | | [API-DocumentationTemplate.md](documentation/API-DocumentationTemplate.md) | Template for documenting the APIs | -| [API-Readiness-Checklist.md](documentation/API-Readiness-Checklist.md) | A checklist that describes the minimum criteria for considering an API Ready | -| [Camara_Versioning_Guidelines.md](documentation/Camara_Versioning_Guidelines.md) | Guidelines for API Subprojects on making releases | | [Glossary.md](documentation/Glossary.md) | A glossary of the common terms and their API parameter/field names for use in the APIs | | [API-Testing-Guidelines.md](documentation/API-Testing-Guidelines.md) | Guidelines for the API testing in CAMARA project | +NOTE: Guidelines for Release Management of API versions, e.g. the API-Readiness-Checklist, are located within [ReleaseManagement](https://github.com/camaraproject/ReleaseManagement). The versioning of APIs is defined within the [API-design-guidelines.md](documentation/API-design-guidelines.md#5-versioning). + ## Status and released versions From eadd6808d32c80092fbf734075690efb1947b9fb Mon Sep 17 00:00:00 2001 From: Maximilian Laue Date: Thu, 13 Jun 2024 22:25:10 +0200 Subject: [PATCH 14/25] feat: add minItems: 1 for subscription-types --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index da60c107..b4b0edef 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -308,6 +308,7 @@ components: Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array + minItems: 1 items: type: string config: @@ -487,6 +488,7 @@ components: Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided at API project level. type: array + minItems: 1 items: type: string config: From 85ceb7a78e718766edf33f2b9a1059a385540130 Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Fri, 14 Jun 2024 00:18:44 +0200 Subject: [PATCH 15/25] Update API-design-guidelines.md Shilpa's comment on URL version --- documentation/API-design-guidelines.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index d770181a..5963179b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -581,7 +581,16 @@ servers:     url: {apiRoot}/qod/v2 ``` -NOTE: CAMARA exceptionally allows to use both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in initial API versions (x=0) in the API version in the URL. +--- + +IMPORTANT: CAMARA initial public APIs (see explanation below) shall use both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in the API version in the URL. + +--- + +```yaml +servers: +    url: {apiRoot}/number-verification/v0.3 +``` This allows for test and usage of initial API versions as they are evolving rapidly, e.g. /qod/v0.10, or /qod/v0.11alpha1. However, it should be acknowledged that any initial API version may change. From 8f1ffc691d9992b06a70d6a29d62b385405b32aa Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:20:01 +0200 Subject: [PATCH 16/25] Update API-design-guidelines.md included updates on removing"-" in release names some more tweeks --- documentation/API-design-guidelines.md | 38 +++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 5963179b..06e0d013 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -27,10 +27,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [4.1 URL Definition](#41-url-definition) - [4.2 Input/Output Resource Definition](#42-inputoutput-resource-definition) - [5. Versioning](#5-versioning) - - [5.1 API version (OAS Info object)](#51-api-version-oas-info-object) + - [5.1 API version (OAS info object)](#51-api-version-oas-info-object) - [5.2 API version in URL (OAS servers object)](#52-api-version-in-url-oas-servers-object) - [5.3 API versions throughout the release process](#53-api-versions-throughout-the-release-process) - - [5.4 Backwards and Forward Compatibility](#54-backwards-and-forward-compatibility) + - [5.4 Backward and forward compatibility](#54-backward-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) @@ -541,16 +541,16 @@ These considerations are below: Versioning is a practice by which, when a change occurs in the API, a new version of that API is created. -API versions use a numbering scheme in the format: x.y.z +API versions use a numbering scheme in the format: `x.y.z` * x, y and z are numbers corresponding to MAJOR, MINOR and PATCH versions. * MAJOR, MINOR and PATCH refer to the types of changes made to an API through its evolution. * Depending on the change type, the corresponding number is incremented. * This is defined in the [Semantic Versioning 2.0.0 (semver.org)](https://semver.org/) standard. -### 5.1 API version (OAS Info object) +### 5.1 API version (OAS info object) -The API version is defined in the "version" field (in the Info object) of the OAS definition file of an API.  +The API version is defined in the `version` field (in the `info` object) of the OAS definition file of an API.  ```yaml info: @@ -568,13 +568,13 @@ In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH versio For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the CAMARA wiki.  -It is recommended to avoid breaking backwards compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. +It is recommended to avoid breaking backward compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. ### 5.2 API version in URL (OAS servers object) -The OAS file also defines the API version used in the URL of the API endpoint (in the servers object). +The OAS file also defines the API version used in the URL of the API (in the `servers` object). -The API version in the URL only includes the "x" (MAJOR version) number of the API version as follows: +The API version in the `url` field only includes the "x" (MAJOR version) number of the API version as follows: ```yaml servers: @@ -583,7 +583,7 @@ servers: --- -IMPORTANT: CAMARA initial public APIs (see explanation below) shall use both the MAJOR and the MINOR version number (v0.y) separated by a dot (".") in the API version in the URL. +IMPORTANT: CAMARA public APIs with x=0 (`v0.x.y`) MUST use both the MAJOR and the MINOR version number separated by a dot (".") in the API version in the `url` field: `v0.y`. --- @@ -592,7 +592,7 @@ servers:     url: {apiRoot}/number-verification/v0.3 ``` -This allows for test and usage of initial API versions as they are evolving rapidly, e.g. /qod/v0.10, or /qod/v0.11alpha1. However, it should be acknowledged that any initial API version may change. +This allows for both test and commercial usage of initial API versions as they are evolving rapidly, e.g. `/qod/v0.10alpha1`, `/qod/v0.10rc1`, or `/qod/v0.10`. However, it should be acknowledged that any initial API version may change. ### 5.3 API versions throughout the release process @@ -600,10 +600,10 @@ In preparation for its public release, an API will go through various intermedia Overall, an API can have any of the following versions: -* work-in-progress (wip) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. -* alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes -* release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug fixing purposes -* public (x.y.z) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states:  +* work-in-progress (`wip`) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. +* alpha (`x.y.z-alpha.m`) API versions (with extensions) for CAMARA internal API rapid development purposes +* release-candidate (`x.y.z-rc.n`) API versions (with extensions) for CAMARA internal API release bug fixing purposes +* public (`x.y.z`) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states (used in release management):  * initial - indicating that the API is still not fully stable (x=0) * stable - indicate that the API has reached a certain level of maturity (x>0) @@ -624,9 +624,9 @@ Precedence examples: For more information, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management project Wiki. -### 5.4 Backwards and Forward Compatibility +### 5.4 Backward and forward compatibility -Avoid breaking backwards compatibility, unless strictly necessary, means that new versions should be compatible with previous versions. +Avoid breaking backward compatibility, unless strictly necessary, means that new versions should be compatible with previous versions. Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account: @@ -636,7 +636,7 @@ Bearing in mind that APIs are continually evolving and certain operations will n - Remove deprecated APIs documentation. - Never start using already deprecated APIs. - Types of modification: +Types of modification: - Not all API changes have an impact on API consumers. These are referred to as backward compatible changes. - In case of such changes, the update produces a new API version that increases the MINOR or PATCH version number. @@ -660,9 +660,9 @@ Breaking changes to an API that **DO** affect consumers: - Modifying or removing a mandatory parameter in existing operations (resource verbs). For example, when consulting a resource, a certain field is no longer returned. Another example: a field that was previously a string is now numeric. - Modifying or adding new responses to existing operations. For example: creating a resource can return a 412 response code. - Compatibility management +Compatibility management: -Tho ensure this compatibility, the following must be followed. +To ensure this compatibility, the following guidelines must be applied. **As API provider**: - Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later MAJOR change (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality) From e5b23605c29da977d0bd503f619d230d14d49342 Mon Sep 17 00:00:00 2001 From: Maximilian Laue Date: Mon, 17 Jun 2024 11:02:43 +0200 Subject: [PATCH 17/25] feat: add maxItems: 1 for subscription-types --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index b4b0edef..4b439076 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -309,6 +309,7 @@ components: at API project level. type: array minItems: 1 + maxItems: 1 items: type: string config: @@ -489,6 +490,7 @@ components: at API project level. type: array minItems: 1 + maxItems: 1 items: type: string config: From 0556740d5100ded447efa1e8e8f9e55a10fa109a Mon Sep 17 00:00:00 2001 From: tanjadegroot <87864067+tanjadegroot@users.noreply.github.com> Date: Mon, 17 Jun 2024 13:01:48 +0200 Subject: [PATCH 18/25] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix typo Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 06e0d013..293d0d95 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -648,7 +648,7 @@ Backward compatible changes to an API that **DO NOT** affect consumers: - Adding a new endpoint - Adding new operations on a resource (`PUT`, `POST`, ...). - Adding optional input parameters to requests on existing resources. For example, adding a new filter parameter in a GET on a collection of resources. -- Changing an input parameter from reqmandatory to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. +- Changing an input parameter from mandatory to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. - Adding new properties in the representation of a resource returned by the server. For example, adding a new age field to a Person resource, which originally was made up of nationality and name. Breaking changes to an API that **DO** affect consumers: From ee43515db5cb103e767edff255dd82d462a54aa2 Mon Sep 17 00:00:00 2001 From: Maximilian Laue Date: Mon, 17 Jun 2024 15:07:51 +0200 Subject: [PATCH 19/25] feat: add `SUBSCRIPTION_DELETED` as new terminationReason for CloudEvents --- artifacts/camara-cloudevents/event-subscription-template.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/artifacts/camara-cloudevents/event-subscription-template.yaml b/artifacts/camara-cloudevents/event-subscription-template.yaml index da60c107..9af71314 100644 --- a/artifacts/camara-cloudevents/event-subscription-template.yaml +++ b/artifacts/camara-cloudevents/event-subscription-template.yaml @@ -633,11 +633,13 @@ components: - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached + - SUBSCRIPTION_DELETED - Subscription was deleted by the requester enum: - MAX_EVENTS_REACHED - NETWORK_TERMINATED - SUBSCRIPTION_EXPIRED - ACCESS_TOKEN_EXPIRED + - SUBSCRIPTION_DELETED HTTPSubscriptionRequest: allOf: From 0eb1d3fed3ff00a2bcce93245fbd883f89dc0e7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 12:52:31 +0200 Subject: [PATCH 20/25] merge main --- artifacts/CAMARA_common.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 3f257ff2..f18ebc33 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -58,11 +58,14 @@ components: * `ipv4Address` * `ipv6Address` * `phoneNumber` + * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. type: object properties: phoneNumber: $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: @@ -75,6 +78,11 @@ components: pattern: '^\+[1-9][0-9]{4,14}$' 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 + example: "123456789@domain.com" + DeviceIpv4Addr: type: object description: | From 4ae03bb1d76be80243badfdce988a8b254df0b76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 13:02:39 +0200 Subject: [PATCH 21/25] Apply middle way agreement --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index f18ebc33..392dc53d 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -59,7 +59,8 @@ components: * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + NOTE2: for the Commonalities meta-release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the meta-release work is done and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: From c1418449ffec79d3a020cb9fcb3fd1e93051fc41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:09:44 +0200 Subject: [PATCH 22/25] Apply Shilpa's suggestion --- artifacts/CAMARA_common.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 392dc53d..74c8dcaf 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -60,7 +60,7 @@ components: * `phoneNumber` * `networkAccessIdentifier` NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. - NOTE2: for the Commonalities meta-release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the meta-release work is done and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: From fb61a6c9493e6d973c1d2813f5e43d829df94fd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:31:49 +0200 Subject: [PATCH 23/25] Add further clarification on 3-legged scenarios where device can be omitted --- documentation/API-design-guidelines.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 3eec0103..95972c87 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -30,8 +30,11 @@ This document captures guidelines for the API design in CAMARA project. These gu - [5.1 Versioning Strategy](#51-versioning-strategy) - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - - [### 6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) - - [### 6.2 Error Responses - Device Object](#62-error-responses---device-object) + - [6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) + - [6.2 Error Responses - Device Object](#62-error-responses---device-object) + - [Templates](#templates) + - [Response template](#response-template) + - [Examples template](#examples-template) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) - [8.1 Pagination](#81-pagination) @@ -43,6 +46,8 @@ This document captures guidelines for the API design in CAMARA project. These gu - [10.2 Security Implementation](#102-security-implementation) - [11. Definition in OpenAPI](#11-definition-in-openapi) - [11.1 General Information](#111-general-information) + - [Info object](#info-object) + - [Servers object](#servers-object) - [11.2 Published Routes](#112-published-routes) - [11.3 Request Parameters](#113-request-parameters) - [11.4 Response Structure](#114-response-structure) @@ -51,6 +56,9 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Inheritance](#inheritance) - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) + - [OpenAPI security schemes definition](#openapi-security-schemes-definition) + - [Expressing Security Requirements](#expressing-security-requirements) + - [Mandatory template for `info.description` in CAMARA API specs](#mandatory-template-for-infodescription-in-camara-api-specs) - [11.6.1 Scope naming](#1161-scope-naming) - [APIs which do not deal with explicit subscriptions](#apis-which-do-not-deal-with-explicit-subscriptions) - [Examples](#examples) @@ -1814,6 +1822,7 @@ response: The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. +Note: With the current 3-legged authorization flows, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (that can optionally include a port). ```md # Identifying a user device from the access token From 00684b47bc6e9e54fcff488b56406d3048885778 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:36:39 +0200 Subject: [PATCH 24/25] minor fixes --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 95972c87..a60586b7 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1822,7 +1822,7 @@ response: The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. -Note: With the current 3-legged authorization flows, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (that can optionally include a port). +Note: With the current 3-legged authorization flows used by CAMARA, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). ```md # Identifying a user device from the access token From d4d44f5b72675d10192bc8fdceb21b299f576ec9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Wed, 19 Jun 2024 15:46:24 +0200 Subject: [PATCH 25/25] Apply Herbert's suggestions --- documentation/API-design-guidelines.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index a60586b7..e1873d19 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1820,14 +1820,14 @@ response: ## Appendix A: `info.description` template for `device` identification from access token -The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. +The documentation template below is recommended to be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. Note: With the current 3-legged authorization flows used by CAMARA, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). ```md -# Identifying a user device from the access token +# Identifying a device from the access token -This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. This mechanism reduces the need for multiple identifiers and extensive validation. +This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. ## Handling of device information: @@ -1848,10 +1848,10 @@ This specification defines the `device` object field as optional in API requests ### Restrictions for tokens without an associated authenticated identifier: - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. +``` By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. -``` -Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a user device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. +Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make `device` object more interoperable and usable for API consumers.