In todays world, APIs are everywhere. From your business application to your best friend's online store, to your smart kettle that makes a coffee from that handy app on your phone. Everything needs to talk to something else at some point, and this is where, as Software Engineers, we would reach for an API. We use them to send updates to your kettle or provide a catalog of products for the online store, or an entry point into the masses of data that your business application may need.
 

Over the last ten years APIs have been becoming more and more of a necessity, as the mobile web introduced the need for faster applications and websites. This meant as Software Engineers, we needed to look for ways to provide data for these applications and websites quickly when requested - instead of as the application or page opens.
 

As time has gone on, our APIs have been growing in complexity, growing in terms of the functionalities that they offer, and the footprint of the data they capture has changed time after time. This is where API versioning can help you manage the growth and changes in your application as you move forward with business as usual.
 

If you provide an API to a smart kettle for example, changes to your API could mean 100s or 1000s of people suddenly cannot make their morning cup of coffee. Or people are unable to checkout from that online store, resulting in decreased sales. Event not getting the correct or up to date information from your business application, leading to misinformed decisions, and potentially missed leads.
 

As you can imagine, not versioning your API correctly can have a detrimental impact on your business or product.
 

 

So before we begin, let’s dive into what exactly is API Versioning. It is an approach we as Software Engineers will use to introduce changes to our API, it is as simple as that. We may want to change how the data is structured, or how functionality works, or add extra authorisation layers to increase security in areas that were overlooked. There are other approaches we can take to do some of these tasks, such as Role Based Access Control or Feature Flags. However, usually we would want to use these alongside Versioning of our API to get the fine-grained control we desire for our application.
 

Let’s take the smart kettle scenario. We may release another kettle that uses the same API, that wants to optionally heat the water to a different temperature. Our initial product heating the water to 100 degrees to make a coffee, but from product feedback with our customers - our product is mostly used by tea drinkers who only want to heat the water up to 80 degrees, to make the perfect cup of tea. This in itself is perhaps a separate article on making the perfect cup of tea. Our initial product used version 1 of our API, that only let you heat up the water to 100 degrees. We could amend this and add a default temperature of 100 degrees, but that wouldn’t let us add customisations for users who wanted that option.
 

If we implemented versioning into our API, our new product release could be timed with the release of a new version of our API - allowing all new kettles to talk directly to the new endpoints required. Then we can stagger updates to our older products, to upgrade them to use the newer API - offering the new functionality to all customers with a supported product. Allowing customers with unsupported products to still use the product as they always have. Having this level of seamless compatibility means that our customers are going to have the best experience they can with our brand - increasing the likeliness of them being a returning customer in the future.
 

If we didn’t version our API, or plan this level of role out using a versioned API - we could end up pushing customer loyalty and trust away from us. While this may be an extreme case of not versioning your API, it is a reality that this could indeed happen. Even if you don’t have immediate plans to release additional products, or change functionality - do you want to have to worry about it later on when you are about to add that massive new feature, or change the massive feature that helped you grow your user base to begin with?

URL Versioning
 

One of the most popular approaches is URL versioning. This is where you would see something like https://api.domain.com/v1/some-resource in your URL. This is sometimes referred to as Path Versioning too. The idea here is that you are allowing users to choose which version they want to access easily by modifying to URL itself. There are a lot of benefits to this approach. It offers simplicity out of the box, allowing you to simply nest a new version of the API in the same domain without any additional thoughts. You can even host this behind an Nginx reverse proxy to allow different servers to host different versions of your API. However, it isn’t without its down sides. Using a versioned API that uses URL Versioning means that you can easily end up with duplicate code - no matter which programming language or framework you choose to use. You are adding complexity on-top of complexity and binding it together through one entry point - the URL. Now this is something that you can work around if you have the time to do so, but it is not the most real expectation.

Media Type Versioning
 

Not as popular as URL Versioning, however it has been increasing in popularity since companies such as GitHub switched to using this approach. With this approach we use the requests Accept header to determine which version of the API you want to communicate with. This does add a limit to who might be able to change or update the version, as not everyone will be able to change request headers - or know how they should be formatted. If we are to follow API Standards, then we would expect to see something such as Accept: application/vnd.api.version+json where version is the version being requested. If we were to build a fully RESTful API then we will already be doing content negotiation to determine how our user wants the response to be sent back. However adding the additional complexity of versioning into that makes it all that much harder to build your API efficiently.
 

Query Parameter Versioning
 

Query Parameters are something a lot of us are familiar with then it comes to APIs, but not so much for versioning. The benefit of using query parameters for versioning is that it is easy to implement, and change at any point. Query Parameters are super flexible and have fantastic support in all web and application clients. Much like media type versioning this can add additional layers of complexity on-top of what you are building already. Alongside content negotiation, data filtering and sorting, adding API versioning into the query parameters adding yet another thing you have to logic checks for at a point when you should be focusing more on fine tuning the response you want to get back.