...
| Info | ||
|---|---|---|
| ||
API versioning is done using SemVer 2.0.0: vx.y.z with x, y and z being numbers indicating MAJOR, MINOR and PATCH versions. In addition to the target public API versions x.y.z, internally to the CAMARA project during the API release process version extensions are used for pre-releases (described in the section below):0.10.0
Finally,
|
The following types of API versions are used throughout an API's release process:
...
- First, using wip in the API version, develop your API until it is sufficiently stable to create a first alpha API version 0.1.0-alpha.1.
- Create one (or more) alpha API versions to stabilize the API.
- Create the first release-candidate API version proposed for testing (for the M3 milestone (stable proposed API version for testing).
- Create one (or more) release-candidate API versions following feedback from testers (between the M3 and the M4 milestone following feedback from testersmilestones).
- Create the final release-candidate public API version proposed for the meta-release (for the M4 milestone (version proposed for public release).
- Finally, create publish the public API version version (in the meta-release).
| Info | ||
|---|---|---|
| ||
| All alpha and release-candidate API versions are INTERNAL to the CAMARA project and meant to be used only for the API development and release management process. Usage for other purpose is at the user's own risk. |
...
- API version type: refers to the stage in the API release processlife cycle: wip, alpha, release-candidate or public.
- API version: (without or with an extension) is what is put in the version field in the API OAS definition file.
- NOTE: a public API version shall never have an extension.
- API version in URL (initial/stable): is a lowercase "v" followed by the MAJOR number from the API version. This is put in the URL field in the Servers object in the API OAS definition file.
- NOTE: for an initial API version (x=0), the API version in the URL is exceptionally allowed to contain both the MAJOR and the MINOR version numbers (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 during the release process of an API version.
| API version types in the release process | API version (OAS Info object) | initial (x=0) API version in URL (OAS Servers object) | stable (x>0x>=1) 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 pre-release) |
| release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal pre-release) |
public | x.y.z | v0.y | vx | Yes (release) |
Precedence examples for API versions throughout the release process:
...
- provide an access to the new API version definition file (via a link or dedicated endpoint)
- if possible, do the same to obtain the currently implemented API version definition file
Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account:
- Agree to discontinue an API version with consumers.
- Establish the obsolescence of the API in a reasonable period (6 months).
- Monitor the use of deprecated APIs.
- Remove deprecated APIs documentation.
- Never start using already deprecated APIs.