API versioning

The term API version refers to what is written in the version field of an API OAS definition file.

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 definition of terms used and the description of the life cycle stages of the API version.

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 versions.

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:

Alternative proposal, addressing the comment on vxalpham and vxrcn for initial versions:

Precedence examples: 

• 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.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.

API version life cycle stages

work-in-progress (wip) API version

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

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 (x.y.z alpha.m) is an intermediate API version with changes with respect to a previous API version.
• 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

The purpose of a release-candidate API version is to allow for (only) bug fixing encountered during further API implementation testing. 

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

The purpose of a public-release API version is that it can be used by organization outside CAMARA in application development.

• 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 API version is considered to be not yet stable, and is referred 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

A public-release API version is called "initial" to indicate that this API version has not yet reached full maturity, but is considered stable enough to have a public-release as part of a meta-release. It is expected that in the next meta-release this API version becomes stable.

• 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 public-release 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:  

  • An update due to a breaking change in a public-release API version 0.y.z results in a next API version: 0.y+1.0. Example: 0.9.0 → 0.10.0

  • An update due to 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 towards the updated public-release API version.

The use of initial public-release API versions can be used in commercial applications, but the user shall expect that subsequent API versions may require code changes to their applications.

stable public-release API version

A public-release API version is considered "stable" once it has been deployed by at least 2 operators.

• Stable public-release API versions are API versions released after the stability of the API version has been demonstrated through
  • certification of the API in at least 2 commercial contexts
  • availability and use of the API in at least 2 commercial deployments.
• 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.

Stable public-release API versions are the ones recommended for use in commercial applications. The user can expect that subsequent API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.

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  a new release with 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.
• After meta-release approval, create the release for the new public-release API version 1.1.0, with its release tag rx+1.n and release package ("latest")).

If there is a real need to support multiple public-release API versions, 2 consecutive major versions should be the maximum (this is by experience, not a convention or requirement).

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.

Breaking and non-breaking changes

Semantic versioning on breaking changes:

• breaking changes imply a major version increment (that's the fundamental part)
• semver FAQ entry: https://semver.org/#if-even-the-tiniest-backward-incompatible-changes-to-the-public-api-require-a-major-version-bump-wont-i-end-up-at-version-4200-very-rapidly

What is a breaking change?

• turning an optional attribute into a mandatory one
• modifying or removing a mandatory attribute (breaks existing payloads)
• modifying or removing an endpoint (breaks existing queries)

What is a non-breaking change?

• turning a mandatory attribute into an optional one
• adding an optional attribute
• adding a new endpoint

How to avoid breaking changes?

• never change an endpoint name; instead, add a new one and mark the original one for deprecation in a minor release and remove it in a later major release (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality)
• if possible, do the same for attributes

Make the information available:

• provide an access to the API spec (via a link or dedicated endpoint)
• if possible, do the same to obtain the implemented API spec version