...
All API versions of a given meta-release shall be aligned to the Commonalities and Identity and Consent Management releases that are part of that same meta-release.
...
API
...
version tag
An API version
...
The following picture gives an overview of the API versions that an API can go through from inception to release.
The following section describe the details on naming, release assets, and the steps to produce a public-release API version as part of a meta-release.
...
tag is a GitHub tag placed on the main or a selected branch to allow locating the corresponding API version in the repository.
API version release package
An API version release package is created using the GitHub release mechanism. It consists in a zip file that has a snapshot of the API Sub-project repository with the content located using the API version's tag.
Releasing API versions
API version throughout the release process
During the development, release preparation and release of an API version,
- multiple intermediate pre-releases for initial, alpha or release-candidate API versions may be created, and
- a final public-release API version is created.
...
The following picture gives an overview of the API versions that an API can go through from inception to release.
The following section describe the details on naming, release assets, and the steps to produce a public-release API version as part of a meta-release.
API release assets & naming conventions
For a given API version, its release consists in creating the following set of API release assets :
- the API version in the OAS version field in the API definition file
- the API major version in the URL defined in the API definition file
- the API version GitHub tag on that branch api-x.y.z, with extension as applicable
- a GitHub release package, tagged "latest" or "pre-release", containing the API Sub-project repo for the branch
In case of multiple APIs managed in the same API Sub-project, each API shall be developed in a separate folder.
Release are handled per API, and the API name is part of the tags names to distinguish releases of APIs in the same API family.
To create an API version (pre-)release, the API (pre-)release assets need to be created with naming rules as indicated in the below table.
...
GitHub tag
(api = API name)
...
GitHub release package (name = GitHub tag)
...
none
-alpha.m
-rc.n
...
v0.y.z (exception)
v0alpham
v0rcn
...
api-0.y.z
api-0.y.z-alpha.m
api-0.y.z-rc.n
...
optional
...
optional
...
with naming as indicated in the below table.
| API version type | API version (OAS file) | API version extension (OAS file) | API version in URL (OAS file) | API version tag (GitHub) (api = API name) | API version release package (name = API version tag) (GitHub) | API version release package tag |
|---|---|---|---|---|---|---|
| initial (x=0) | 0.y.z | none -alpha.m -rc.n | v0.y.z (exception) v0alpham v0rcn | api-0.y.z api-0.y.z-alpha.m api-0.y.z-rc.n | optional | optional [ pre-release ] |
| alpha | x.y.z | -alpha.m | vxalpham | api-x.y.z-alpha.m | optional | optional [ pre-release ] |
| release-candidate | x.y.z | -rc.n | vxrcn | api-x.y.z-rc.n | mandatory | pre-release |
| public-release | x.y.z | none | vx | api-x.y.z | mandatory | latest |
| work-in-progress | wip | N/A | vwip | N/A | N/A | N/A |
In the above API release asset table, the column headers mean the following:
- the API version (OAS file) is the version field of the API OAS definition file
- the API version extension (OAS file) is the extension that can be added to the version field of the API OAS definition file
- the API version in URL (OAS file) is the a "v" followed by the API major version number placed in the URL field of the API OAS definition file
- the API version tag is the GitHub tag put on the main or update branch allowing to retrieve the API version, e.g. api-x.y.z, with extension as applicable
- the API version release package, tagged "pre-release" or "latest", containing the zipped version of the whole API Sub-project repository.
In case of multiple APIs managed in the same API Sub-project, each API shall be developed in a separate folder.
Release are handled per API, and the API name is part of the tags names to distinguish releases of APIs in the same API family.
To create an API version (pre-)release, the API (pre-)release assets need to be created with naming rules as indicated in the below table.
This is illustrated in the following figure:
...
- With the exception of initial API versions, all pre-release API versions must have an API extension.
- An initial or alpha API version may have a GitHub release package, which must have the "pre-release" tag
- A release-candidate and public-release API version must have a GitHub release package
- Only the latest release packages of an API version may have the tag "latest".
Exception cases
Usually an API an API will go through the above described evolution API version steps.
However, there are some exceptions that may occur and are suggested to be handled as described below.
steps in the evolution of its version.
However, for For initial API versions (with x=0), there are some exception cases that may occur. The below table provides guidelines on how to handled the API version in these cases:
| API version | next API version for breaking change |
|---|
...
| next API version for non-breaking change | |
|---|---|
| api-0.y.z |
...
...
api-0.y |
...
+1.0 | api-0.y.z+1 |
...
...
| api- |
...
| 0.y.z–alpha.m |
...
api- |
...
0.y+1. |
...
0- |
...
alpha. |
...
1 | api- |
...
0.y.z+1 |
...
-alpha.1 |
...
| api- |
...
| 0.y. |
...
| z-rc.n | api- |
...
0.y+1.0-alpha.1 |
...
| api-x.y+1.0-alpha.1 |
Special case: initial API versions (0.y.z)
...