Page History

...

Exception: For initial API versions 0.y.z, the second version number full version 0.y.z may be include in the URL, e.g. v0.y.z, to simplify testing of API implementations during API development. In this exception case the dot (".") is kept for readability reasons. See initial API version section below for exception examples.

initial API version

• Initial API versions only exist for new APIs. They are API versions with x = 0 (API versions 0.y.z-extension.n)
• An initial API version may exist for several minor version numbers without extensions, but should at some point mature in an initial alpha API version 0.y.z-alpha.1
• During initial API version development, the API version in the URL shall include the full version number v0.y.z (with dots) to enable testing during rapid development. The guideline is that the y number is increased with breaking changes, the z number is increased with non-breaking changes. (see alos the exception below).

• Exception: for initial alpha or release-candidate API versions:  

  • A breaking change results in an API version change from 0.y.z-extension.n to an API version: 0.y+1.0. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.10.0

  • A non-breaking change results in an API version change from 0.y.z-extension.n to an API version. 0.y.z+1. Example: 0.9.0-alpha.m or 0.9.0-rc.n → 0.9.1
  • After this, -alpha.m and -rc.n extensions can again be applied throughout the API version development.
• Once a first public-release API version x.y.z has been created (x > 0), no further initial API versions (x = 0) are allowed.

...

• A public-release API version (x.y.z with x>0) is a major/minor/patch stable version of an API published as part of a meta-release.
• A public-release API version provides the relevant public items of the release checklist.
• A next public-release API version is introduced if there are updates to the API definition (major/minor/patch).
• The update of a public-release API version needs to be carefully announced and discussed with API consumers.
• A public-release API version is part of a CAMARA meta-release

...

work in progress API version

A developmenet version of an API is any of the following API versionswork in progress API version may exist for an API during the merge of PRs applied to an API:

• Vxan initial API version apiname-0.y.za alpha API version apiname-x.y.z-alpha.m:  any API version (with or without extension) to which changes are to be applied through PR(s).
• Vnext: the tag of the next version with respect to Vx.y.z after the PRs have been applied.
• This can be applied to any Vx.y.z as needed for patches, updates or evolutions.
• The first/all PRs shall setthe version field of the APIOAS definition file(s) to “wip”.
• This wip verions shall remain until the project maintainers decide to tag the API as Vnext
• If the Vx.y.z has an associated release package, a release packages shall be created for Vnext.
• Only maintainers can create development branches.
• Other developers should fork the repo and do PRs from there.
• All PRs shall be approved by maintainers before being merged.
• Once all PRs are merged, the last PR shall updated the version field of the API OAS definition file(s) to Vnext
• The Vnext release tag shall be applied

pre-release

A pre-release refers to a release-candidate API version apiname-x.y.z-rc.m.

...

To create an API version (pre-)release, the API (pre-)release assets need to be created with naming rules as indicated in the below table.

This is illustrated in the following figure:

...