The API Release Process describes the creation of (pre-)releases of API versions throughout the API lifecycle, and for a given meta-release.
For a meta-release, the API Release Process targets the release of public API versions, aligned with the corresponding Commonalities and ICM public versions.
| Info |
|---|
IMPORTANT API release numbers are decoupled from API version numbers. API releases are just numbered sequentially, while API versions follow the API versioning guidelines. |
...
An API Sub Project can release as many alpha and release-candidate API versions as useful for API development and testing. In between releases, the API version is set to "wip" (to indicate that this API version should not be used).
| Info |
|---|
IMPORTANT Pre-releases (for alpha or release-candidate API versions) available in the CAMARA GitHub can be freely used, BUT AT THE USER'S OWN RISK. |
...
copy the API-Readiness-Checklist.md file(s) to the API Sub Project repository in the <home>/documentation/API_documentation folder.
rename the file to include <API name> as prefix plus a dash ("-") e.g. quality-on-demand-API-Readiness-Checklist.md
provide each release asset as indicated in the column corresponding to the release type
for an available asset
update the Status column with "Y" (yes) if the release asset is available or fulfilled in the current release, or "N" (no) otherwise. Example: an intermediate pre-release may not yet provide all mandatory release assets for the release type.
update the Comments Reference Information column with the relative link to the asset in the repository (if applicable), and any other additional links or comments as needed
For the point 12: you can copy the following link if your previous API version has been certified: GSMA OGW Portal.
NOTE: the checklists of a public API version and of its preceding release-candidate and the checklist of a subsequent public API version may can be the same.
Checklist explanation
The following table explains each of the release assets expected to be delivered in the API release.
Nr | API release assets | Explanation |
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 located in the home/ code/API_definition folders of the API Sub Project repository and validated using the linting rules in point 6. |
2 | Design guidelines from Commonalities applied | This refers to the guidelines in the applicable references the applicable release of the Commonalities / documentation / guidelines from the Commonalities repository, in particular the API-design-guidelines.md. A subset of these design guidelines have been mapped to corresponding linting rules as described in Commonalities / documentation / Linting-rules.md, which can shall be executed against the OAS API definition file once linting is enabled for the Sub ProjectAPI repository. 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 Projects shall verify data type alignment with those in the the Commonalities / artifacts / CAMARA_common.yaml file |
3 | Guidelines from ICM applied | This refers to the guidelines described in the documents available in the applicable references the applicable release of the IdentityAndConsentManagement / documents folder and guidelines from the IdentityAndConsentManagement repository, and to the related Commonalities linting rules provided by ICM that are successfully executed against the OAS API definition file.(provided to Commonalities) 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. |
4 | 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 Commonalities / documentation / API-design-guidelines.md document. |
5 | API documentation | The API specification shall include all the documentation needed documentationby the API consumer. It shall include the mandatory authentication and authorization text as defined in the section on security as described in the API Design Guidelines-design-guidelines.md. Any explanatory 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. |
6User Stories | User Stories (it is recommended to have at least 2) | User Stories need to be documented by the API Sub Project team. It is recommended to have at least 2 different User Stories. User Stories shall follow the template found here: Commonalities / documentation / Userstory-template.md and be located in the home /documentation/API_documentation folder of the API Sub Projectrepository. Please note that User Stories shall be provided when an API is first submitted to the CAMARA API backlog / documentation / APIbacklog.md. |
7 | Basic API test cases & documentation | At least one Gherkin feature file is shall be provided for the API in the /code/Test_definitions folder of the API Sub Project repository covering sunny day scenarios and main error cases (of course you may provide more if available). Details Guidance can be found in the Commonalities / documentation / API-Testing-Guidelines.md. 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 /code/Test_definitions folder of the API Sub Project repository covering sunny and rainy day scenarios. Details can be found in the Commonalities / documentation / API-Testing-Guidelines.md. Enhanced tests are required for a stable public - release. |
9 | Test result statement | A statement in a discussion issue of the API Sub Project References the scope issue (or any other relevant issue) for the API version that contains a statement 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: API Release Process - section on API release numbering |
11 | Change log updated | The changelog needs to be provided following the template which can be copied from here: ReleaseManagement / documentation / CHANGELOG_TEMPLATE.md. A good example usage of the template is the the following: QualityOnDemand/CHANGELOG.md. Please refer to the more recent releases using the release numbering scheme (rx.y). |
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. |
Note 1: User Stories are being handled when submitting an API to the API backlog (see here). It is recommended to have at least 2 user stories, which need to be documented by the API Sub Project team. User Stories shall follow the template : from Commonalities / documentation / Userstory-template.md and be located in the home /documentation/API_documentation folder of the API Sub Projectrepository.
Note 2: the addition of a Security review release asset beyond the Commonalities linting rules is for further study.
Readiness checklist per API version
...
Nr | API release assets | alpha | release- candidate | initial public (v0.y.z) | stable public (vx.y.z, x>=1) | Status | Reference information |
1 | API definition | M | M | M | M | link | |
2 | Design guidelines from Commonalities applied | O | M | M | M | Comm. release nr | |
3 | Guidelines from ICM applied | O | M | M | M | ICM release nr | |
4 | API versioning convention applied | M | M | M | M | x.y.z | |
5 | API documentation | M | M | M | M | link | |
6 | User Stories | O | O | O | M | link | |
7 | Basic API test cases & documentation | O | M | M | M | link | |
8 | Enhanced API test cases & documentation | O | O | O | M | link | |
9 | Test result statement | O | O | O | M | link | |
10 | API release numbering convention applied | M | M | M | M | rx.y | |
11 | Change log updated | M | M | M | M | link | |
12 | Previous public - release was certified | O | O | O | M | link |
...
Technically, an API (pre-)release is created using the GitHub release feature (see Draft/publish a new release). It involves
A GitHub issue defining the scope of the target API version.
A release PR associated to this issue.
After release PR approval:
a release tag (with the tag name following the API release numbering guidelines above) on the main or on a maintenance release branch.
a release package containing the API's repository with the corresponding API release assets for each contained API version (zip file). A release package is optional for pre-releases of alpha API versions.
...