...
Check Info object
version: aligned with the released API version and formatted correctly (per Commonalities)
description: check that it
contains sufficient in-line API documentation
does not use Telco Jargon / abbreviations (non blocking for release if in documentation), e.g. avoids use of
"customer", unless explicitly explained what is meant. Instead use as applicable “API consumer”, (application) “end-user”, or whatever else is applicable.
"Telco/operator/CSP", as also Aggregators, etc. may expose the API. Use a more general term e.g. “API exposure platform owner” as applicable.
"subscriber". Use “Device” or “End-user” (defined as the application user) as applicable
“API customer”: use “API consumer” or (application) “end-user”, as applicable
contains the mandatory text from the section on authentication and authorization from the ICM CAMARA-API-access-and-user-consent.md.
contains the x-camara-commonalities version from the Commonalities release referenced in the API readiness checklist. This should be following the same versioning scheme as in the API URLs. so e.g. “x-camara-commonalities: 0.5”
Check servers object has the correct version format e.g. v0.xrc1, v1rc1, v0.x or v1.
Check security schemes: check presence and format (OIDC) and scope name format.
In externalDocs: this field is optional, but recommend to point to the CAMARA API repository.
description: Project documentation at CAMARA repository
url: https://github.com/camaraproject/<api-repository>Ensure that error cases are sufficiently explained in in-line documentation in info.description field.
...
API definition file (see details above)
commonalities is respected
availability of linting report in release issue
ICM is respected (see below)
versioning (checked in yaml) is aligned with guidelines
documentation (beyond in-line)
check for Telco jargon / abbeviations (same as in API definition details above)
user stories - check for Telco jargon / abbeviations (same as in API definition details above)
basic test files (for M3)
cover 2xx response and all error responses (tbc)
enhanced test files (for M4)
cover all error responses
release numbering is aligned with guidelines
changelog (see details above)
certification - for stable public APIs - check GSMA reference.
Commonalities updates (Spring25)
| Github file macro | ||||
|---|---|---|---|---|
|
See also: Version 0.5.0 supporting documentation - CAMARA Project - CAMARA Project
ICM updates (Spring25)
| Github file macro | ||||
|---|---|---|---|---|
|
Release actions - details
...
For APIs that are targeting to become a stable public API, for M3, the Release Management team shall request a review by Commonalities and ICM teams.
...
ICM team review - details
THese These points are taken from: https://github.com/camaraproject/IdentityAndConsentManagement/issues/189#issuecomment-2315026741 )
...
- Check the ICM-defined
info.descriptiontemplate (Authorization and Authentication section). Reference
Example: Checked https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r1.2/code/API_definitions/simple-edge-discovery.yaml#L203 - Check the use of openIdConnect for
securitySchemes. Reference
Example: Checked https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r1.2/code/API_definitions/simple-edge-discovery.yaml#L391 - Check the use of the
securityproperty according to ICM definitions. Reference
Example: Checked the one endpoint
https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r1.2/code/API_definitions/simple-edge-discovery.yaml#L253 - Error codes are defined by Commonalities e.g. INVALID_TOKEN_CONTEXT.
Example: https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r1.2/code/API_definitions/simple-edge-discovery.yaml#L551
However, the ICM could check the definition of a 403 INVALID_TOKEN_CONTEXT if it applies to a specific API (e.g. APIs using device object or phoneNumber in the API request). Reflects an inconsistency between information in some field of the API request and the access token. - ⚠️ OK with comments. The API specification has its own section Identifying the Device. The API specification does not include the recommended section called "Identifying a device from the access token" in
info.descriptionthat provides a detailed description of the expected handling of thedeviceobject in the API request as it relates to the access token. It is specified in Appendix A: info.description template for device identification from access token and it is required for APIs that use thedeviceobject in the API requests.
@Kevsy @crissancas @javierlozallu please check whether the recommended section is applicable - Verify that there is no unexpected leakage of users' personal information, such as API responses containing identifiers or information beyond the API functionality.
Example: OK SimpleEdgeCloud , the API can be used to verify a phone number like NumberVerification does. Please see API misuse Commonalities#259. If Phone-Number is part of the SimpleEdgeCloud API request then response tells the API consumer the same as a request to NumberVerification does.
- For APIs including a device object, check that Appendix A of the API-Design-Guidelines.md is respected:
info.descriptiontemplate fordeviceidentification from access token
...
Q&A
Who can approve the M3 release PR ? Code Owners after RM approval is noted in the release PR or its issue.
When to create a RM review issue ? when When the release-management_maintainers list is included as a reviewer in a release PR.
When do I tick a review issue task ?
Review actions: tick after checking the related file(s) and putting the review comment(s) in the PR/PR issue about the(se) files. Also put just OK for the file if no comments.
Also put a comment in the review issue with the major review comments and the overall state of the API.
Release actions: tick when task is done.
When do we close the review issue ? When all tasks in the review issue are ticked as done. Close as completed.
Question: should Should we add a milestone label so we can filter on it later ?
How to know if an APIs API is covered by RM ? Use a comment in the comment fields of the API release tracker, visible on the Meta-release pageOnce a review issue is created it links to the PR. and should be visible in the comments.
Is there a way to know if an API requires consent request ? No, this is local regulation. It is covered when using the security scheme and the scope rules.
Open questions
should the test file files contain the API version number ? e.g. Feature: CAMARA Call Fowarding Signal API, v0.1.0 - Operation call-forwardings - is it required to include the version (as people forget to update it) As the tests are in the same release package, can the version number be avoided in the test features ?
can we automate test generation for an API - which tools ? - which ensures that all API spec errors/cases are covered by the tests ?
add guideline to use error codes in scenario names ?