This content is part of the Essential Guide: The API lifecycle: A look at planning to production

API versioning with the Semantic Versioning specification

While developers have some flexibility in the versioning schema they use for internal projects, it's important to establish an easily understandable standard for API versioning.

As a developer, how many different application versioning schemata have you used in your career so far? Three,...

maybe four?

In my experience, when it comes to anything remotely non-technical, establishing some sort of accepted standard is the only way to ensure consistency (and sanity) in your projects. Unfortunately, some problems are a bit less of a priority than others, so the effort that goes into finding a solution can vary wildly from organization to organization.

This sentiment is doubly true when it comes to API versioning. While a versioning schema you use for internal projects (or even fully open sourced projects) can be pretty flexible, the schema you follow for your API needs to be something your users can understand easily.

Semantic Versioning specification

As the name implies, the Semantic Versioning specification (SemVer) is a standardized specification for determining why and how to update your application's version number. SemVer is one of the best standards I have discovered as a developer because it is so easy to follow and greatly reduces decision paralysis in my own applications.

The SemVer specification itself is a list of 11 rules to follow when versioning your application. I won't address all of them (although I highly recommend you read and internalize them on your own), but I will go over the basic structure of a version number: X.Y.Z (or Major.Minor.Patch).


Starting from the bottom up, the Patch (Z) version of your API identifies the number of backwards-compatible bug fixes that have been introduced into your API under a current Minor version (explained below). Under SemVer guidelines, a bug is defined as an "internal change that fixes incorrect behavior."


The Minor (Y) version of your API identifies the number of new and backwards-compatible functionality that is introduced to your API or an event where any functionality is marked as deprecated (but not yet removed). This number can also be incremented if any internal improvements or patch-level changes are introduced within the code.


Finally, the Major (X) version of your API is incremented only when backwards-incompatible changes are added to your API. In an event where a change is going to break any previously defined functionality in your API, no matter how big or small, the Major version must be increased.

It is important to note that whenever Major or Minor versions are incremented, the other versions must be reset to zero. This ensures that every version clearly conveys the number of changes contained within them.

While that's all pretty straightforward, the first thought that usually occurs to developers when implementing SemVer is "what version do I start with?"

The schema you follow for your API needs to be something your users can understand easily.

If you do a search, you'll end up with four different answers (1.0.0, 0.1.0, 0.0.1 and 0.0.0), but according to the SemVer FAQ, you should start your versioning at 0.1.0. What this does is indicate that a project is not considered stable yet (stable means the Major version is at least 1), while conveying that there is new functionality and no bug fixes yet.

So how do we take SemVer and use it in a way that is simple and comfortable for our users without overloading them with unnecessary information? The simple answer here is to reference a full X.Y.Z version number in your API documentation and using only the Major version in the actual API implementation (as is common).

This can be tough because API structure is weird. Surely there are a ton of proposed best practices out there, but even major providers have wildly different API designs. As a result, there are half a dozen different ways to convey the current version of your API to your users.

My personal preference for conveying API versioning from within an API is to put the Major version in the URL path ( I've heard a few reasons against this, the biggest one being that changing the Major version of your API changes the endpoint URL entirely. But I find it to be a good approach to deal with end-life support of backwards-incompatible API versions.

The advantage of using only the Major version from within your API itself is that it can be an indicator to your users that their implementation will work as long as the version of their API is available. As a developer, it is incredibly frustrating to consume an API that releases a backwards-incompatible change without updating the Major version number.

It's worth noting that while SemVer can completely eliminate the process of thinking about versioning, it can also kill debates on whether it's time to "bump up the API version." Unless backward-incompatible functionality is introduced, it is definitely not the time to bump the version up.

The Semantic Versioning specification is not just a great tool to improve efficiency and reduce ambiguity within your organization about application versioning. It is also a great way to give your application and your users the respect they deserve. Following a predictable, well-documented versioning specification ensures that your API matches expectations while also reassuring users that the API's functionality won't change without proper notice.

Next Steps

Here are five tips for better API versioning

Learn how to hammer out your cloud API management strategy

Discover how to keep things on track when building an API portfolio

Dig Deeper on Distributed application architecture