Semantic versioning
Distinguish between major, minor and patch versions.
Versioning an API using Semantic Versioning (semver.org) allows for breaking changes, non-breaking enhancements and fixes to be easily communicated.
Semantic versioning allows for tight coupling between the API contract and its version, and is advantagous where the API contract has been rigorously defined, such as with OpenAPI.
Due to the nature of semantic versioning, releases are logically related to each other in a branching tree, rather than as a simple linear progression over time. This can make communicating changes through a changelog more difficult.
The version is typically applied to the API as a whole, rather than specific endpoints or resources.
Pros
- Developers can easily determine if a new version contains a breaking change.
- Alpha, beta and release candidate versions can be distingushed from general availability versions.
- The versioning scheme will be familiar to developers as it has been adopted by a large amount of projects.
Cons
- For frequently updated APIs, the minor and patch version numbers may grow very high.
- Because versions are not based on time, it may not be apparent which version was released most recently. For example, patches can be released to older branches at any time.
Usage
A version number consists of a major, minor and patch version, for example 2.1.7.
Developers may target the "latest" minor or patch version by omitting them:
| Specifed version | Target version |
|---|---|
2 | Targets the latest version, 2.1.7. |
2.1 | Targets the latest version, 2.1.7. |
2.0 | Targets the latest patch version of the 2.0 branch, e.g. 2.0.8. |
2.1.6 | Targets version 2.1.6 exactly. |
Implementation notes
During initial development the version typically starts at 0.1.0. One released to production, the first publicly-available version would be 1.0.0.
OpenAPI reference
{ "openapi": "3.1.0", "info": { "title": "Semantic Versioning API", "version": "2.1.7" } }