Page History

...

Once a public-release API version is created and published as part of a meta-release, the API version in the URL of a released API the public-release API version shall ONLY contain the MAJOR digit of the API version, e.g. "v2" in the above example.

For alpha and release-candidate API versions, the API version extension shall be included in the URL, but without any hyphens or dots.

Example: in the URL of an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1.

Exception: For initial API versions 0.y.z, the full version 0.y.z may be include in the URL, e.g. v0.y.z, to simplify testing of API implementations during API development. In this exception case the dot (".") is kept for readability reasons. See initial API version section below for exception examples.

...

The API name used in this document is the segment in the url field in the OAS definition file before the segment holding the API version.

Example: for the above url: "{apiRoot}/qod/v2", the API name is qod.

initial API version

• Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z-extension.n)
• An initial API version may exist for several minor version numbers without extensions, but should at some point mature in an initial alpha API version 0.y.z-alpha.1
• During initial API version development, the API version in the URL shall include the full version number v0.y.z (with dots) to enable testing during rapid development. The guideline is that the y number is increased with breaking changes, the z number is increased with non-breaking changes. (see alos also the exception below).

• Exception: for initial API versions:  

  • A breaking change results in an API version change from 0.y.z-extension.n to an API version: 0.y+1.0. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.10.0

  • A non-breaking change results in an API version change from 0.y.z-extension.n to an API version. 0.y.z+1. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.9.1
  • After this, -alpha.m and -rc.n extensions can again be applied throughout the API version development.
• Once a first public-release API version x.y.z has been created (x > 0), no further initial API versions (x = 0) are allowed.

...

• An alpha API version (extension alpha.m) is an intermediate API version with changes with respect to a previous alpha API version.
• The purpose of an -alpha API version is to support rapid development of an API and testing of its implementation for testing feedback purposes.
• An alpha API version provides the relevant alpha items of the readiness checklist.
• An alpha API version cannot be part of a CAMARA meta-release. 
• It needs to go through the below API pre-release and release steps first.

...

• A release-candidate API version (extension -rc.n) is a pre-release version of an API with stabilized changes with respect to the latest which is stabilized and intended to become the next public-release API version.
• The purpose of a pre-release API version is to provide a more stable version and prepare the API readiness for public-release as part of a meta-releasefor implementation and API testing. It shall be used to create the test results and to show it meets the acceptance criteria.
• A release-candidate API version provides the relevant rc items of the release checklist.
• A release-candidate API version cannot can only be part of a CAMARA meta-release after approval by the Release Management team. 
• For a release-candidate API version to be accepted for public-release in a given meta-release, it needs to provide all the public-release items on the release checklist.
• Once the release-candidate API version is approved by the release management process for publication as part of a meta-release, the public-release API version is created.

...

A work in progress API version may exist for an API during the merge of PRs applied to an API:

...

time that PRs are merged to a given API version:

pre-release

A pre-release refers to a release-candidate API version apiname-x.y.z-rc.m.

A pre-release has an associated GitHub release package with a "pre-release" tag.

public-release

A public-release API version is an API version meeting all checklist requirements such that it can be published as part of a meta-release.

NOTE: all CAMARA development and pre-release API versions are also publicly available and can be used, but changes may happen to such API versions without notice.

release

An API release can refer to either a release-candidate or a public-release version of an API.

meta-release

A meta-release is a set of public-release API versions made available at a given point in time (September and March).

All API versions of a given meta-release shall be using the Commonalities and Identity and Consent Management releases that are part of that same meta-release.

Releasing API versions

API version throughout the release process

The following picture gives an overview of the API versions that an API can go through from inception to release.

Image Added

The following section describe the details on naming, release assets, and the steps to produce a public-release API version

pre-release

A pre-release refers to a release-candidate API version apiname-x.y.z-rc.m.

A pre-release has an associated GitHub release package with a "pre-release" tag.

public-release

A public-release API version is an API version meeting all checklist requirements such that it can be published as part of a meta-release.

NOTE: all CAMARA development and pre-release API versions are also publicly available and can be used, but changes may happen to such API versions without notice.

release

An API release can refer to either a release-candidate or a public-release version of an API.

meta-release

A meta-release is a set of public-release API versions made available at a given point in time (September and March).

All API versions of a given meta-release shall be using the Commonalities and Identity and Consent Management releases that are part of that same meta-release.

Releasing API versions

API version throughout the release process

The following picture gives an overview of the API versions that an API can go through from inception to release.

Image Removed

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

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.

A release requires the creation of an associated set of API release assets.

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 Github branch for the API version: apiname-x.y.z, with extension as applicable
• the API version tag on that branch apiname-vx.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 apiname is part of the branch and tags names to distinquih 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.

API release assets & naming conventions

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.

A release requires the creation of an associated set of API release assets.

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 Github branch for the API version: apiname-x.y.z, with extension as applicable
• the API version tag on that branch apiname-vx.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 apiname is part of the branch and tags names to distinquih 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.

...

• 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".

Special case: initial API versions (0.y.z)

A newly introduced API is in the main branch and has API version 0.1.0.

The API version v0.y.z handling is slightly different from API versions > 0, as one or more working branches for initial API versions may be created differing in the minor version number during initial API development in the v0 context without creating GitHub release packages for these branches. Branch names are apiname-0.y.z, and optionally creating release packages for these branches. 

Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.1 < 0.3.0, etc.

Once an API version 0.y.z is deemed sufficiently stable, a first apiname-0.y.z-alpha.1 branch shall be created with the corresponding GitHub release package.

From this point onward, the below API (pre-)release steps apply.

...

• -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".

Special case: initial API versions (0.y.z)

A newly introduced API is in the main branch and has API version 0.1.0.

The API version v0.y.z handling is slightly different from API versions > 0, as one or more working branches for initial API versions may be created differing in the minor version number during initial API development in the v0 context without creating GitHub release packages for these branches. Branch names are apiname-0.y.z, and optionally creating release packages for these branches. 

Examples: 0.1.0 < 0.1.1< 0.2.0 < 0.2.1 < 0.3.0, etc.

Once an API version 0.y.z is deemed sufficiently stable, a first apiname-0.y.z-alpha.1 branch shall be created with the corresponding GitHub release package.

From this point onward, the below API (pre-)release steps apply.

The first public-release API version v1.0.0 is created from the last agreed and accepted API version apiname-0.x.y-rc.n

Developing an API

• Vx.y.z:  any API version (with or without extension) to which changes are to be applied through PR(s).
• Vnext: the tag of the next version with respect to Vx.y.z after the PRs have been applied.
• This can be applied to any Vx.y.z as needed for patches, updates or evolutions.
• The first/all PRs shall setthe version field of the APIOAS definition file(s) to “wip”.
• This wip verions shall remain until the project maintainers decide to tag the API as Vnext
• If the Vx.y.z has an associated release package, a release packages shall be created for Vnext.
• Only maintainers can create development branches.
• Other developers should fork the repo and do PRs from there.
• All PRs shall be approved by maintainers before being merged.
• Once all PRs are merged, the last PR shall updated the version field of the API OAS definition file(s) to Vnext
• The Vnext release tag shall be applied

Preparing an API (pre-)release

...

• Develop the 1.1.0 update on the main branch
• Once sufficiently stable, create a new branch apiname-1.1.0-alpha.1. 
• Several intermediate alpha branches may be created, with or without release packages,
• Then one or more intermediate release-candidate API versions (rc branches + release packages) may be created (see example table below).
• The last release-candidate API version will be proposed for meta-release. 
• After meta-release approval, create the apiname-1.1.0 branch and release package ("latest") for the new public-release API version 1.1.0.

work in progress API version

API family

The notion of API family will not be managed as part of release management. CAMARA releases only consider API versions.

...