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 is 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 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 wip 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.

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

• the API version type references the life cycle stages of an API: wip, alpha, release-candidate and public-release.
• the API maturity is an indicator of the maturity of a given public-release API version: initial or stable. 
• the API version, without or with an extension, is what is put in the version field in the API OAS definition file.
• the 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, its 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 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. 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 public-release 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) 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.
• A public-release API version provides the relevant public-release assets of the API release checklist.

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.

Evolution of a public-release API version

Evolution 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 evolution 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 non-backward compatible / breaking changes to the API
• changes in the minor (y) number when creating backward compatible changes to the API
• changes in the patch (z) number when correcting an error of the API

During the development of an API version update, all pre-release API versions need to get a version extension so its release can be managed properly.

Example for a backward-compatible 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
• Once sufficiently stable, create a new API version api-1.1.0-alpha.1 by tagging the main branch
• Several intermediate alpha API versions 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 new public-release API version 1.1.0 for public-release (tag and release package ("latest")).

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.

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