Page History

...

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

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

...

• API version type: refers to the stage in the release cycle of an API: wip, alpha, release-candidate and public-release.
• API version: (without or with an extension) is what is put in the version field in the API OAS definition file.
  • NOTE: a public-release API version shall never have an extension in the API version field.
• API version in URL (initial/stable): is a lowercase "v" followed by the MAJOR number from the API version. This is in the URL field in the Servers object in the API OAS definition file.
  • an exception is for an initial public-release API version (with x=0) where CAMARA allows that the URL may contain also the MINOR version number (separated by a "." (dot): v0.y.
• API version can be released: A release can be created for the API version (with or without (for alpha) a release package).

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

The following table gives the values of the API version (Info object) and the API version in the URL (servers object) used in the release process of the API. THe API version in the URL is different for initial API versions (x=0) and stable API versions (x>0).

Precedence examples:

...

• 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0.
• 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)

...

API version

...

in URL

The OAS API definition file contains the URL definition for the API endpoint which includes the version of the API with the following format:

• A lowercase "v" followed by the MAJOR number from the API version, e.g. for qod v2.1.0, it will be v2 as follows:

servers:

    url: {apiRoot}/qod/v2


• Once a stable public-release API version is created, the API version in the URL shall ONLY contain "vx", and never include an extension

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: https://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.

...

• .
• Exception: For initial public-release API versions

...

• 0.y.z, the second version MINOR number (y) may be include included 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 . A dot (".") is used for readability.
  • in this stage of the API development, y is used to indicate 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.
  • to indicate MINOR (non-breaking) changes. Patches, if needed would also increase z. 
• 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.

API name

The API name used in this document is the segment in the 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

...

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

...

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 MAJOR number (x → x+1) number when creating breaking /  nonnon-backward compatible updates of the API
• changes in the minor MINOR number (y → y+1) number when creating non-breaking backward compatible updates of the API
• changes in the patch PATCH number (z → z+1) 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  in a new release with API version 1.1.0:

...

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

...

To implement very small MINOR or PATCH updates of a public-release API

...

version, a maintenance branch shall be created,

• A dedicated maintenance branch shall

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 Issues and Pull Request (PRs) and committed to the this maintenance branch.
• The update results in a maintenance release for the public-release API version.
• The version of the resulting updated API version shall follow the semver rules.

• The updates of API for the maintenance release will be merged into a next MAJOR or bigger MINOR API updates. 

Breaking and non-breaking changes

...

Make the information available:

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