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