Definitions

API version

The API version is defined in the "version" field of the OAS definition of an API. Its content must follow Semantic Versioning 2.0.0 | Semantic Versioning (semver.org).

An API version has the format:  x.y.z  where x, y and z are numbers corresponding to MAJOR, MINOR and PATCH releases.

The following bullets are extracted of the semver 2.0 specification (and links to the corresponding spec item):

• Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. https://semver.org/#spec-item-4
• Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. https://semver.org/#spec-item-5

  • Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. https://semver.org/#spec-item-6

  • Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. 

  • Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

Precedence example:  1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0.

The CAMARA API guidelines describe the applicable versioning strategy. NOTE: if this proposal is accepted, some updates of the guidelines may be needed.

API version extensions

During API development and release preparation, API version extensions are used to identify intermediate stable versions of an API.  

The API version extension is added to the "version" field of the OAS definition of an API, as well as to the URL (see below table). Its content must follow the here described syntax and semantics.

The following API version extensions may be be used in the API version:

• alpha API versions: -alpha.m
• release-candidate API versions: -rc.n
• no extension - this is allowed only for initial API versions 0.y.z (with x=0).

Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers starting at 1.

All extensions must have a number (so just "-alpha" or "-rc" is not allowed) and should be minimally "-alpha.1" or "-rc.1".

The notions of alpha and release-candidate API versions, and their related API version extensions, are INTERNAL to the CAMARA project and used only for the API development and release management process.

Precedence example: 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (public-release)

NOTE: a public-release API version shall have no extension in the API version field of the OAS definition file, only the major.minor.patch version number as described in the previous section.

API version in URL

The API guidelines contain the following approach for defining the API endpoint URL:

servers:
  - url: "{apiRoot}/qod/v2"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root

The apiRoot is to be adapted by the implementer of the API endpoint (the API provider).

Once a public-release API version is created and published as part of a meta-release, the API version in the URL of 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 second version number (y) may be include in the URL, e.g. qod/v0.y, to simplify testing of API implementations during initial API development.
• In this exception case, the y is used for major (breaking) changes, and the z is used for minor (non-breaking) changes. 
• The dot (".") is kept for readability reasons. See initial API version section below for exception examples.

API name

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, with or without version extension)
• An initial API version may exist for several minor version numbers without extensions, but should at some point mature to become an initial alpha API version: api-0.y.z-alpha.1
• During initial API version development, the API version in the URL shall also include the y version number v0.y (with dots). This is to simplify the testing of different initial API versions..
• In initial API versions, the y number is increased with breaking changes, the z number is increased with non-breaking changes (see 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 initial API version development.
• Once a first public-release API version x.y.z has been created (x > 0), normally no further initial API versions (x = 0) shall be created.

alpha (alpha) API version

• An alpha API version (extension  alpha.m) is an intermediate API version with changes with respect to a previous API version.
• The purpose of an -alpha API version is to support rapid development of an API and testing of its implementation for feedback purposes.
• An alpha API version provides the relevant alpha items of the readiness checklist. A release package is optional.
• 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.

release-candidate (rc) API version

• A release-candidate API version (extension -rc.n) is a pre-release of an API version which is stabilized and intended to become the next public-release API version.
• The purpose of a release-candidate API version is to allow for (only) bug fixing encountered during further API implementation testing. It shall be used to create the API test results and all required release assets. - moved to next bullet - remove this bullet - questing on test results is still valid.
• A release-candidate API version shall provides all relevant rc items of the release checklist, such as API test results.
• A release-candidate API version proposed for a meta-release needs to provide all the public-release items on the release checklist.
• The final release-candidate API version needs to go through TSC approval such that its corresponding public-release API version can be prepared and included in the meta-release.

public-release API version

• A public-release API version (x.y.z with x>0) is a major/minor/patch stable version of an API. It is referred to as an incubated API version.
• A public-release API version with x=0 may exist. It is referred to as a sandbox API version. 
• A public-release API version is published as part of a CAMARA meta-release.
• A public-release API version provides the relevant public items of the release checklist.
• A next public-release API version is introduced if there are updates to the API definition (major/minor/patch).
• The update of a public-release API version needs to be carefully announced and discussed with API consumers.
• Minor updates or patches to a released API results in the creation of a maintenance branch with its own releases as needed.
• Cumulative minor changes shall be released in the next meta-release, following the normal release process.
• A patch release replaces the released API version in the existing meta-release.

sandbox API version

incubated API version

pre-release

The term pre-release can be used to refer to any of the initial, alpha or release-candidate releases of an API version.

NOTE: all pre-release API versions 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

The term release can be used to refer to either a pre-release or a public-release of an API version.

meta-release

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

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.

release tag

A release tag is a GitHub tag placed on the main or a maintenance branch to allow locating the corresponding API version in the repository.

release package

A release package is a zip file created using the GitHub release mechanism together with the release tag. It contains a snapshot of the API Sub-project repository with the content indicated by the release tag.