This section gives an overview of the proposed handling of API versions and their relation to release management.
It consolidates inputs from
- Rafal's proposal for the CAMARA API Maturity Levels - proposal - CAMARA Project - Confluence.
- the inputs from Consolidation Issue for open points release management · Issue #9 · camaraproject/ReleaseManagement (github.com).
- Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)
- Open Issues Consolidated - CAMARA Project - Confluence
This page was briefly discussed on the RM call of 2024-03-19. Initial feedback was:
- use work in progress "-wip.n" and release candidate "-rc.n" extensions instead of alpha and beta as the latter are not easy to define. These extensions would be only used internally in CAMARA for release management, but not in released APIs, which should only have SenVer numbers.
- API implementers are free to use these non-released versions as they see fit, but there is no guarantee from CAMARA side that they will not change.
API versioning
API version
The API version is defined in the "version" field of the OAS definition of an API. Its content MUST follow Semantic Versioning 2.0.0 | Semantic Versioning (semver.org).
An API version has the format: x.y.z where x, y and z are numbers corresponding to MAJOR, MINOR and PATCH releases.
The following provides some extracts of the semver 2.0 specification (and links to the corresponding spec item):
- Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. https://semver.org/#spec-item-4
- Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. https://semver.org/#spec-item-5
Patch version Z (x.y.Z | x > 0) MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. https://semver.org/#spec-item-6
Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backward compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented.
Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.
Precedence example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.
The API guidelines describe the applicable versioning strategy.
API version extensions
During the API development and release preparation, "work-in-progress" (-wip) or "release-candidate" (-rc) extensions may be used to identify intermediate states of an API.
The notions of work-in-progress and release-candidate API versions are internal to the CAMARA project and used in the release management process.
The following extensions shall be used in the API version:
- -wip.m
- -rc.n
Extensions are post-fixed to the API version numbers and separated from it by a hyphen "-". m and n are numbers.
Precedence example: 1.0.0-wip.1 < 1.0.0-wip.2 < 1.1.0-wip.1 < 1.1.0-wip.2 < 1.1.0-rc.1 < 1.2.0-rc.2 < 1.2.0 (released)
API version creation
To create an API version, the following assets need to be creates with naming rules as indicated in the below table.
API version | GitHub branch | Tag | GitHub release package | Github release package tag |
---|---|---|---|---|
work-in-progress | release-x.y.z-wip.m | vx.y.z-wip.m | release-x.y.z-wip.m | pre-release |
release-candidate | release-x.y.z-rc.n | vx.y.z-rc.n | release-x.y.z-rc.n | pre-release |
release | release-x.y.z | vx.y.z | release-x.y.z | latest |
An API sub-project can create as many work-in-progress API versions as they want.
A release-candidate API versions shall be created for an API version as follows:
- At the M3 release milestone: when its definition is agreed by the API sub-project, before API testing as required by the release management process will be applied. As a result of testing, changes may be made to the release-candidate API version and one or more additional release-candidate API versions may be created.
- At the M4 release milestone: the final release-candidate API version is delivered for the meta release approval.
A released API version is created when the API is approved for a meta release. This removes the extension from the API version.
- At the M5 release milestone, the final API version is released and included in the meta release.
Example
The following table illustrates the usage of versions and version extensions throughout the API lifecycle.
The API version 0 life cycle is slightly different from API versions > 0.
release milestone | API version field | API version extension | API version in URL | release branch name | release branch tag | release package name | release tag | later: PR annotation |
---|---|---|---|---|---|---|---|---|
API devt. | 0.9.0 | v0 | release-0.9.0 | v0.9.0 | release-0.9.0 | development | ||
API devt. | 0.10.0 | -wip.1 | v0wip1 | release-0.10.0-wip.1 | v0.10.0-wip.1 | release-0.10.0-wip.1 | development | |
M3 | 0.10.0 | -rc.1 | v0rc1 | release-0.10.0-rc.1 | v0.10.0-rc.1 | release-0.10.0-rc.1 | pre-release | |
M4 | 0.10.0 | -rc.2 | v0rc2 | release-0.10.0-rc.2 | v0.10.0-rc.2 | release-0.10.0-rc.2 | pre-release | |
M5 | 1.0.0 | v1 | release-1.0.0 | v1.0.0 | release-1.0.0 | latest | ||
.... | ||||||||
M5 | 2.0.0 | v2 | release-2.0.0 | v2.0.0 | release-2.0.0 | latest | ||
API devt. | 2.1.0 | v2 | release-2.1.0 | v2.1.0 | release-2.1.0 | development | ||
API devt. | 2.2.0 | V2 | release-2.2.0 | v2.2.0 | release-2.2.0 | development | ||
API devt. | 2.3.0 | -wip.1 | v2wip1 | release-2.3.0-wip.1 | v2.3.0-wip.1 | release-2.3.0-wip.1 | development | |
API devt. | 2.4.0 | -wip.2 | v2wip2 | release-2.4.0-wip.2 | v2.4.0-wip.2 | release-2.4.0-wip.2 | development | |
M3 compatible functional extension | 2.4.0 | -rc.1 | v2rc1 | release-2.4.0-rc.1 | v2.4.0-rc.1 | release-2.4.0-rc.1 | pre-release | |
API testing | 2.4.0 | -rc.2 | v2rc2 | release-2.4.0-rc.2 | v2.4.0-rc.2 | release-2.4.0-rc.2 | pre-release | |
M4 | 2.4.0 | -rc.3 | v2rc3 | release-2.4.0-rc.3 | v2.4.0-rc.3 | release-2.4.0-rc.3 | pre-release | |
M5 | 2.4.0 | v2 | release-2.4.0 | v2.4.0 | release-2.4.0 | latest | ||
.... | ||||||||
API devt. non-compatible functional extension | 3.0.0 | -wip.1 | v3wip1 | release-3.0.0-wip.1 | v3.0.0-wip.1 | release-3.0.0-wip.1 | pre-release | |
API devt. non-compatible functional extension | 3.0.0 | -wip.2 | v3wip2 | release-3.0.0-wip.2 | v3.0.0-wip.2 | release-3.0.0-wip.2 | pre-release | |
M3 | 3.0.0 | -rc.1 | v3rc1 | release-3.0.0-rc1 | v3.0.0-rc1 | release-3.0.0-rc1 | pre-release | |
M4 | 3.0.0 | -rc.2 | v3rc2 | release-3.0.0-rc2 | v3.0.0-rc2 | release-3.0.0-rc2 | pre-release | |
M5 | 3.0.0 | v3 | release-3.0.0 | v3.0.0 | release-3.0.0 | latest |
API version in URL
The API guidelines contain the following approach for defining the API endpoint URL:
servers:
- url: "{apiRoot}/qod/v2"
variables:
apiRoot:
default: http://localhost:9091
description: API root
The API version in the URL of a released API SHALL ONLY contain the MAJOR digit of the API version, e.g. "v2
" in the above example.
The apiRoot
is to be adapted by the implementer of the API endpoint (the API provider).
Before API release, the API definition and endpoint implementation may reflect the version extension of the API in the API version in the URL, but without any hyphen or dots.
Example: in the URL the version is v2wip1 for API version 2.y.z-wip.1
Ideally such an extension to the API version in the URL should not be needed if the API
API family
The notion of API family will not be managed as part of release management. CAMARA releases only consider API versions.
It is recommended to adopt the proposal to make the API family a working group, and have the API sub-project focus on the development of one or more APIs.
See Herbert's proposal here: Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)
This will reduce the number of meetings and reporting load with the increasing number of APIs, and facilitate moving APIs from one family to another, or combining APIs from multiple families into into into family.