Page Comparison

pre-releaseThe

term A pre-release is used to refer to the a GitHub release of any of the an alpha or release-candidate API versions. Note: the term release can also be used as long as the context is clear.

NOTE: pre-releases are not meant to be included in a meta-release. All pre-releases are publicly available in the CAMARA GitHub and can be used AT THE USER'S OWN RISK, as changes may happen to such API versions without notice.

release

A release refers to the is a GitHub release of a public API version. Releases may be proposed as part of a meta-release.

release of initial public API

Initial public API versions only exists for new APIs. It concerns public APIs versions with x = 0 (0.y.z without version extension).

A public API version is called "initial" to indicate that the API version has not yet reached full maturity, but is considered stable enough to  be proposed for use in applications. However, the user shall be aware that subsequent versions of this API may require code changes to their applications.

Initial public API versions can be

• released outside the meta-release process in order to allow for rapid evolution.
• released as part of a meta-release, after which it is expected that in the next meta-release this API version becomes stable.

release of stable public API

A stable public API version concerns an API version together with all required release assets. They are included in a meta-release.

Stable public API versions are recommended for use in commercial applications. The user can expect that subsequent public API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.

meta-release

A meta-release is a set of public API version releases published together at a given point in time (Spring and Fall).

All API versions of a given meta-release shall be aligned to the releases of the Commonalities and Identity and Consent Management (ICM) documentation included in that same meta-release.

maintenance release

The term maintenance release is used to refer to the release of a patch update of a released public API version.

release tag

1

API definition

This is the OAS API definition file (following the https://spec.openapis.org/oas/v3.0.3 format). It shall be present in the home/code/API_definition folders of the API Sub Project and validated using the linting rules in point 6. 

2

Design guidelines from Commonalities applied

This refers to the guidelines in the API-Design-Guidelines.md document.

A subset of these design guidelines have been mapped to corresponding linting rules provided by Commonalities, that can be executed against the OAS API definition file if linting is enabled for the Sub Project.

For the design guidelines that cannot (yet) be verified by linting rules, the API Sub Project team shall ensure coverage manually. Ideally, a checklist of such guidelines would be provided by the Commonalities team.  In particular, API Sub Project shall verify data type alignment to the Commonalities/artifacts/CAMARA_common.yaml

3

Guidelines from ICM applied

This refers to the guidelines described in the documents available in the IdentityAndConsentManagement / documents folder corresponds to a set of linting rules provided by ICM that are successfully executed against the OAS API definition file. 

Other guidelines that cannot be verified by linting rules shall be covered manually by the API Sub project team. Ideally, a checklist of such guidelines would be provided by the ICM team.

API versioning convention applied

This shall be checked through a linting rule added to the Commonalities rule set on the format of the version field in the OAS API definition file. API versioning is described in the API-Design-Guidelines.md document.

5

API documentation

The API specification shall include all the needed documentation. It shall include the section on security as described in the API Design Guidelines

API documentation beyond the one embedded in the API definition file, shall be located in the home/documentation/API_documentation folder of the API Sub Project. It shall follow the Commonalities/documentation/API-DocumentationTemplate.md 

6

User Stories

User Stories (it is recommended to have at least 2) need to be documented by the API Sub Project team. User Stories shall follow the template: Userstory-template.md and be located in the home/documentation/API_documentation folder of the API Sub Project. Please note that User Stories shall be provided when an API is first submitted to the CAMARA API backlog.

7

Basic API test cases & documentation

At least one Gherkin feature file is provided for the API in the Test_definitions folder of the API Sub Project covering sunny day scenarios and main error cases (of course you may provide more if available). Details can be found in the API Testing Guidelines (in Commonalities GitHub). Basic tests are sufficient for an initial public-release.

8

Enhanced API test cases & documentation

Gherkin feature files are provided for the API in the Test_definitions folder of the API Sub Project covering sunny and rainy day scenarios.  Details can be found in the API Testing Guidelines (in Commonalities GitHub). Enhanced tests are required for a stable public-release.

9

Test result statement

A statement in a discussion issue of the API Sub Project by at least one of the API Sub Project members that the Gherkin feature files have been successfully executed against their (lab) API implementation. 

10

API release numbering conventions applied

This is verified using the information on the release tracker page. The API release numbering is described here: 

11

Change log updated

Change log need to be provided following the template and are located here: link tbd .

12

Previous public release was certified

The previous public API version had at least 1 certified implementation. Reference to at least 1 certification of the API is provided on the GSMA API market launch and certification page.