What is Semantic Versioning?

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, MAJORMINOR, and PATCH, and them 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. 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.

If you liked this video, why don’t you check out Erik’s YouTube channel for more “Getting APIs to Work” content?

Previous articleWhat is network security?
Next articleAxway adds API Management offering to Brazil’s SEC4YOU
Digital Catalyst, Erik works in the Axway Catalyst team and focuses on API strategy, API programs, and API platforms. His main goal is to make sure that organizations make the right decisions for using APIs as the foundation of their digital transformation initiatives. Erik has a Ph.D. from ETH Zurich, is the author of many articles, papers, and books. He is a frequent speaker at global API events and contributes to standardization activities to help improve the way APIs are designed, managed, and used."


Please enter your comment!
Please enter your name here