What Is Semantic Versioning?

Semantic Versioning is a versioning scheme for using meaningful version numbers (that's why it is called Semantic Versioning). Specifically, the meaning revolves around how API versions compare in terms of backwards-compatibility.

Semantic Versioning makes no sense without a well-defined model of how an API can be extended and evolves over time. This needs to be part of the API design and documentation, and it needs to managed as one important aspect of the general API management approach. For this reason, there will be two follow-up pieces about "Managing API Versions" and "Designing APIs for Extensibility and Evolution," but this one here focuses on the narrower topic of identifying versions with the semantic versioning scheme.

Semantic Versioning works by structuring each version identifier into three parts, MAJOR, MINOR, and PATCH, and then putting these together using the familiar "MAJOR.MINOR.PATCH" notation. Each of these parts is managed as a number and incremented according to the following rules:

• PATCH is incremented for bug fixes, or other changes that do not change the behavior of the API.
• MINOR is incremented for backward-compatible changes of the API, meaning that existing consumers can safely ignore such a version change.
• MAJOR is incremented for breaking changes, i.e. for changes that are not within the backwards compatibility scope. Existing consumers have to adapt to the new API, very likely by adapting their code.

There are some additional features for identifying pre-release and build information, but for these (and all other details of the specification), please check out the Semantic Versioning specification.

If you want to learn more about Semantic Versioning, check out the video below. It also discusses Hyrum's law, which is an important pattern in the API space that should be taken into account for setting up API test environments.