Semantic versioning definition
Semantic versioning works by applying three rules to every release. Any change that breaks an existing consumer (removing an endpoint, renaming a field, changing a required parameter) forces a MAJOR bump. Any change that adds new optional functionality (new endpoint, new optional field, new query parameter with a default) forces a MINOR bump. Any change that only fixes a defect without altering observable behavior forces a PATCH bump. The hardest part in practice is deciding what counts as a breaking change, since clients often depend on undocumented behavior.
Semantic versioning (SemVer) is a 3-number versioning convention (MAJOR.MINOR.PATCH) where each segment tells consumers exactly what kind of change they are getting. MAJOR jumps mean breaking changes that require client updates; MINOR jumps mean new features that are backward compatible; PATCH jumps mean bug fixes that change nothing else. Semantic versioning was formalized by Tom Preston-Werner in 2009 and has since become the standard versioning scheme for software libraries and APIs.
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.
What is its purpose?
The purpose of semantic versioning is to make dependency management predictable. Without SemVer, a consumer cannot tell whether upgrading from 1.2.3 to 1.3.0 will break their integration. With SemVer, the version number itself is a contract: a MINOR or PATCH bump is safe to take automatically; a MAJOR bump requires deliberate migration. That contract is what makes large dependency graphs (think npm, pip, Maven) work at all.
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.
See also: What is universal API management and why should I care?
How does semantic versioning work?
Semantic Versioning works by structuring each version identifier into three parts, MAJOR, MINOR, 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:
PATCHis incremented for bug fixes, or other changes that do not change the behavior of the API.MINORis incremented for backward-compatible changes of the API, meaning that existing consumers can safely ignore such a version change.MAJORis 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.
[API Governance Framework] Toward a More Balanced Approach
Dive deeper into semantic versioning and API testing
When to bump major, minor, or patch: a decision guide
Use this shortcut whenever a change is about to ship.
| Change type | Bump | Examples |
|---|---|---|
| Removing or renaming any field, endpoint, or parameter | MAJOR | Delete /v1/users endpoint, rename userId to user_id |
| Changing the type or required-status of an existing field | MAJOR | price goes from number to object, email becomes required |
| Adding a new endpoint, optional field, or optional parameter | MINOR | New /v1/users/me endpoint, optional lastLoginAt field in response |
| Fixing a bug without changing the documented contract | PATCH | Off-by-one in pagination, timezone bug in timestamp serialization |
| Changing the error message format without changing error codes | PATCH | Friendlier error message text |
Semantic versioning for REST APIs in practice
REST APIs add a wrinkle to SemVer that libraries do not have: the version often appears in the URL or in a header, which means every MAJOR bump creates a parallel API surface. Three patterns dominate.
- URL path versioning. /api/v1/orders becomes /api/v2/orders. Easy for clients to understand, but every MAJOR bump duplicates routing and gateway policy.
- Header versioning. Accept-Version: 2 in the request header. Cleaner URLs, but harder to debug and cache.
- Hostname versioning. v2.api.example.com. Maximum isolation between major versions, useful when v1 and v2 have entirely different infrastructure.
Regardless of pattern, the MINOR and PATCH numbers usually stay implicit (the gateway routes all 1.x calls to the latest 1.x release). Only MAJOR changes are visible to clients.
If you want to learn more about Semantic Versioning, check out the video. In it, we also discuss Hyrum’s law, which is an important pattern in the API space that should be taken into account for setting up API test environments.
See how Amplify Enterprise Marketplace simplifies and enhances the developer experience by automatically discovering, capturing, and validating all APIs into one registry.