Page Comparison

work-in-progress (wip)

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 the following information in the API OAS definition file: 
  • Info object - version: wip (instead of x.y.z) 
  • Servers object - url: vwip (instead of vx)
• 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 API version and URL version are set to the next API version.
• 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)

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 release-candidate API version(s) API first.

release-candidate (rc)

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 API implementations and test the API and to create 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.

public-release

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

• A public-release API version (x.y.z) can be more or less mature:
  • A public-release API version with x=0 may exist and is referred as an initial API version.
  • A public-release API version with x>0 is referred to as a stable API version.

initial public-release

Initial public-release API versions only exist for new APIs.

• They are API versions with x = 0 (0.y.z without version extension).
• Exception: for an initial public-release API version, the API version in the URL may also include the y (MINOR) version number v0.y (with the dot). This is to simplify the testing of different initial public-release API versions.

  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

stable public-release

Stable public-release API versions are API versions with x > 0 (x.y.z without version extension).

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.