API versioning

The following types of API versions are used throughout an API's life cycle:

• work-in-progress (wip) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers.
• alpha (x.y.z-alpha.m) API versions (with version extensions) for CAMARA internal API rapid development purposes
• release-candidate (x.y.z-rc.n) API versions (with version extensions) for CAMARA internal API release bug fixing purposes
• public-release (x.y.z) API versions for API versions that are part of a meta-release. These API versions only have API version number x.y.z (semver 2.0), no version extension.

The use of the different API versions throughout the API life cycle is illustrated in the following figure.

The next sections provide the definitions and the description of the release management process for different versions of an API, and illustrates this by examples.

Definitions

API version

The API version is defined in the "version" field of the OAS definition file 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 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 extensions may be be used in the API version:

• alpha API versions: -alpha.m
• release-candidate API versions: -rc.n

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 very first version of an API for which a release can be created is 0.1.0-alpha.1.

All alpha and release-candidate API versions are INTERNAL to the CAMARA project and used only for the API development and release management process.

In the below table, the column headers mean the following:

• API version type: refers to the life cycle stages of an API: wip, alpha, release-candidate and public-release.
• API version maturity: is an indicator of the maturity of a public-release API version: initial or stable. 
• API version: (without or with an extension) is what is put in the version field in the API OAS definition file.
• API version in URL: is a lowercase "v" followed by the API major version number which is what is put in the URL field in the API OAS definition file.
  • an exception is for an initial public-release API version (with x=0) where the URL can contain also the minor version number (separated by a "." (dot) for the 0).

For a given API, the versioning throughout its lifecycle is done as follows:

Precedence examples: 

• 0.1.0 < 0.n.0 < 0.1.0-alpha.1 < 0.1.0-alpha.2 < 0.1.0-rc.1 < 0.1.0-rc.2 < 0.1.0 (initial public-release)
• 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 (stable 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 stable 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 letter "v" followed by the MAJOR number of the API version, e.g. "v2" in the above example.

For initial public-release APIs 0.y.z, the MINOR number may be included in the URL, e.g. v0.y, separated from the MAJOR version by a "." (dot).

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 public-release API versions:

• 0.y.z, the second version number (y) may be include in the URL, e.g. 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 below 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.

work-in-progress (wip) API version

• A work in progress (wip) API version has wip instead of x.y.z as version number in the API OAS definition file, and vwip in the URL.
• The purpose of a work-in-progress API version is to indicate that the API is unstable due to one or more PRs being committed, possibly resulting in temporary inconsistencies.
• A wip API version may exist in 2 cases
  • during the first introduction of a new API upto the creation of the first alpha API version
  • during the time that one or more Pull Requests (PRs) are committed after a given release of an API.
• Between different PR commits, the API version remains "wip".
• After or with the last PR commit, the next API version pre-release is prepared.
• The maintainers of the API decide on the release (or not) of the resulting next API version, implying that its corresponding release assets will be created.

alpha (alpha) API version

• An alpha API version (x.y.z 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 the creation of test implementations for feedback purposes.
• 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 (x.y.z-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 other required release assets.
• A release-candidate API version can be proposed for meta-release. In this case, the public-release API version needs to be prepared in a PR

public-release API version

• A public-release API version (x.y.z) is a major/minor/patch stable version of an API.
  • A public-release API version with x=0 may exist. This is referred to as an initial API version.
  • A public-release API version with x>0 is referred to as a stable API version.
• A public-release API version is published as part of a CAMARA meta-release.
• To be accepted for meta-release, the public-release API version PR needs to go through TSC approval.

initial public-release API version

• Initial public-release API versions only exist for new APIs. They are API versions with x = 0 (0.y.z without version extension).
• An initial public-release API version, the API version in the URL may also include the y (minor) version number v0.y (with a dot). This is to simplify the testing of different initial API versions.
• In initial public-release 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 public-release API versions:  

  • A breaking change in a public-release API version 0.y.z results in an API version: 0.y+1.0. Example: 0.9.0 → 0.10.0

  • A non-breaking change results in an API version change from 0.y.z to API version 0.y.z+1. Example: 0.9.0 → 0.9.1
  • After this, -alpha.m and -rc.n extensions shall again be applied throughout the development of the API.

stable public-release API version

• Stable public-release API versions are API versions released after the stability of the API version has been demonstrated through deployment and use in multiple commercial applications.
• Once a first stable public-release API version x.y.z has been created (x > 0), normally no further initial public-release API versions (x = 0) shall exist.

Update of a public-release API version

Update of a public-release API version need to be carefully planned. This is especially true for breaking changes, but also for non-breaking changes such as new optional functional extensions.

To manage updates of a public-release API version, the semver 2.0 versioning applies to the API version number x.y.z as follows:

• changes in the major (x) number when creating breaking / non-backward compatible updates of the API
• changes in the minor (y) number when creating non-breaking backward compatible updates of the API
• changes in the patch (z) number when correcting an error of the API

Example for a non-breaking update of a public-release API version 1.0.0, resulting in API version 1.1.0:

• Develop the 1.1.0 update on the main branch. The first PR updates the version to wip, and the URL to contain vwip.
• Once sufficiently stable, update the new API version to 1.1.0-alpha.1.
• Several intermediate alpha API versions may be created.
• Then one or more intermediate release-candidate API versions may be created. 
• The last release-candidate API version will be proposed for meta-release. 
• For meta-release approval, create the PR for the new public-release API version 1.1.0.

Maintenance of a public-release API

Once an API has been published as part of a meta-release, situations may occur where minor or patch changes to this API need to be made, without necessarily waiting for the next meta-release.

• In this case a dedicated maintenance branch will be opened for the maintenance of the API.
• The changes are proposed through Pull Request (PRs) and committed to the maintenance branch.
• The version of the resulting updated API version shall follow the semver rules.
• A new public-release API version may be created immediately in the current meta-release, i.e. without waiting for the next meta-release.
• The availability of the new API version should be indicated through the API release tracker page.