API versioning - extension (save)

Owned by Tanja de Groot
Last updated: May 21, 2024
4 min read

From API version extensions definition:

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

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

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.

NOTE: for initial API versions (x=0), the API version in the URL is exceptionally allowed to contain both the MAJOR and the MINOR version numbers (0.y).

API versions inย  release process

API version
(OAS Info object)

initial (x=0) API version in URL (OAS Servers object)

stable (x>0) API version in URL (OAS Servers object)

API version can be released

API versions inย  release process

API version
(OAS Info object)

initial (x=0) API version in URL (OAS Servers object)

stable (x>0) API version in URL (OAS Servers object)

API version can be released

work-in-progress

wip

vwip

vwip

No

alpha

x.y.z-alpha.m

v0.yalpham

vxalpham

Yes (internal)

release-candidateย 

x.y.z-rc.n

v0.yrcn

vxrcn

Yes (internal)

public-release

x.y.z

v0.y

vx

Yes

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)

  • 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0

Definitions

API version types

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.

Initial public-release API versions can be proposed for use in commercial applications, but the user shall be informed 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.