...
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 -release API versions x.y.z, internal internally to the CAMARA project during the API release cycle, process version extensions are used for pre-releases (described in the section below):
Finally,
|
The following types of API versions are used throughout an API's release cycleprocess:
- work-in-progress (wip) API versions used before the first pre-release or between pre-releases. Having "wip" in the API version field indicates that PRs are ongoing and that the API is not usable by API consumers. The first PR should set the API version to wip, and the next "release PR" shall set the API version to the next (semver) x.y.z version.
- alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes
- release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug API bug fixing purposes
- public-release (x.y.z) API versions for publication as part of a meta-release. These usage in commercial contexts. Public API versions only have API version number x.y.z (semver 2.0), no extension. The public -release API can have one of two maturity states:
- initial - indicating that the API is still not fully stable (x=0)
- stable - indicating that the API has reached a certain level of maturity (x>0)
The use of the different API versions throughout the API release cycle process is illustrated in the following figure.
The next sections provide the definition of terms used and the description of the different API version types when moving through the release cyclerelease process.
Table of Contents |
---|
Definitions
...
url: {apiRoot}/qod/v2
- Once a stable public-release API public API version is created, the API version in the URL shall ONLY contain "vx", and never include an extension.
- Exception: For initial public -release API versions 0.y.z, the MINOR number may be included in the URL, e.g. v0.y. A dot (".") is used for readability.
- in this stage of the API development, y is used to indicate MAJOR (breaking) changes, and z is used to indicate MINOR (non-breaking) changes. Patches, if needed would also increase z.
- For alpha and release-candidate API versions, the API version extension shall be included in the URL, but without any hyphens or dots.
- Example: in the URL of an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1.
...
The following tables provides the characteristics of the different API version types that an API will go through during its release cycleprocess.
API version type | Purpose & characteristics |
---|---|
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.
|
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.
|
release-release-candidate (rc) | The purpose of a release-candidate API version is to allow for (only) bug fixing encountered during further API implementation testing.
|
public-release | The purpose of a public -release API version is that it can be used by organizations outside CAMARA in application development and commercial contexts.
|
initial public-release | Initial public -release API versions only exist for new APIs.
|
stable public-release | Stable public -release API versions are public 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. |
Creation of a public
...
API version
To create a public -release version of an API the following steps need to be taken:
- 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 for the M3 milestone (stable proposed API version for testing)
- Create one (or more) release-candidate API versions between the M3 and the M4 milestone following feedback from testers
- Create the final release-candidate API version for the M4 milestone (stable version proposed API version for public -release)Finally, create the public-release API version for public-release and, possibly, for inclusion in the meta-releaserelease)
- Finally, create the public API version
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. |
The below table gives an overview of the API versioning through the release cycleprocess. The column headers mean the following:
- API version type: refers to the stage in the API release cycleprocess: wip, alpha, release-candidate or 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 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).
...
API version types in the 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 for API versions throughout its the release cycleprocess:
- 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 -releaseversion)
- 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 -releaseversion)
Update of a public
...
API version
Updates to a public -release API version can concern MAJOR, MINOR or PATCH changes to the API definition.
- For MAJOR or MINOR changes, the process is the same as for the creation of a public - API version (see previous section), going through alpha and release-candidate API versions to create the update updated public API version.
- For PATCH changes, the API Sub Project can decide to either
- apply the CAMARA API release process, as for MAJOR and MINOR changes resulting in a new API version x.y.z+1
- 1.0.0 → 1.0.1-alpha.1 → ... → 1.0.1-alpha.m → 1.0.1-rc.1 → ... → 1.0.1-rc.n → 1.0.1 (next stable public -releaseversion)
- apply a short cycle to process to create a maintenance-release of the public API version.
- apply the CAMARA API release process, as for MAJOR and MINOR changes resulting in a new API version x.y.z+1
It is recommended to have maximally 2 consecutive public -release API versions available at any given point in time.
...
- never change an endpoint name; instead, add a new one and mark the original one for deprecation in a minor release MINOR change and remove it in a later major release MAJOR (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality)
- If possible, do the same for attributes
- new fields should always be added as optional.
- Postel's Law: “Be conservative in what you do, be liberal in what you accept from others”. When you have input fields that need to be removed, mark them as unused, so they can be ignored.
- do not change the field’s semantics.
- do not change the field’s order.
- do not change the validation rules of the request fields to more restrictive ones.
- if you use collections that can be returned with no content, then answer with an empty collection and not null.
- layout pagination support from the start.
...