BACKGROUND IMAGE: iSTOCK/GETTY IMAGES

This content is part of the Essential Guide: The API lifecycle: A look at planning to production
Evaluate Weigh the pros and cons of technologies, products and projects you are considering.

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).

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."

Minor 

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.

Major

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 (http://your.api.com/v1/endpoint). 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

Join the conversation

3 comments

Send me notifications when other members comment.

Please create a username to comment.

What struggles do you face when it comes to API versioning?
Cancel
This article should be renamed to Versioning standards. There isn't anything semantic about the proposed numbering scheme. On the positive side, I really liked the numbering scheme and will see if I can get it adopted. I disagreed about the path. The description should be readily available from the service without having to know the internals a priori. I suggest a description including the versions, paths and sunset dates be located in a standard location such as /docs/
Cancel
I respectfully disagree.

First of all indicating versions and sub-versions is hardly semantic naming.  There is very little semantic content to be gleaned from 
what would more properly be called numeric indexing.

Second, changing the URI for the service just ensures the untimely breakage of dependent services.  This should be avoided if at all possible, especially since finding appropriate services is still largely a manual process.

Versioning of applications is absolutely a requirement, but that does not mean that the URI to the service has to change.  We need to differentiate between the service and the application.
  
While the adoption of RESTful services has been a boon to web service development by simplifying the interface itself, it does not address the discoverability problem.  This was not within scope of the RESTful specification, perhaps because Dr Fielding assumed that web services would still be registered in UDDI Servers.  Unfortunately, in the process of adopting REST, industry considered SOAP and everything associated with it to be obsolete.  As a result we have lost the ability to find web services once they are developed.

Since, there is no consistent means of locating web services or finding out what they do, when a URI changes due to versioning (as proposed above), dependent services will simply break and recovery will be capricious at best.

The better approach is to leave the URI to the API interface the same, and direct usage to various applications providing this service by the use of switches within the method call.

Adding documentation in a consistent manner, such as returning them from an HTTPs://Get/docs would allow automated collection and indexing of web services, which would go a long way towards averting breakages when APIs change.
Cancel

-ADS BY GOOGLE

SearchSoftwareQuality

SearchAWS

SearchCloudComputing

TheServerSide.com

Close