APIs exist in a strange duality. On the one hand, you’re creating a digital product for software developers to integrate. However, your product is also the data itself and the access to it. With so many developers depending on a stable version of the service, making changes to an API could quickly raise issues. With traditional software, bugs are usually fixed between versions. However, with APIs, designers often don’t have that luxury.

API versioning is how you deal with this contradiction. A proper API versioning strategy ensures an API version remains functional when you enact changes on the code. It also means that API consumers using older versions of the API won’t experience any breaking change. By communicating change effectively, consumers have plenty of time to update their integrations accordingly.

We’ve put together a guide to API versioning. We’ll introduce how API designers can create versions of their APIs and offer some examples of why API versioning is a good idea. We’ll also look into when API versioning isn’t a good idea!

When To Create An API Version

By and large, it’s fairly cut-and-dry when to create a new API version — any time you change your API. There’s more to it than that, though.

More specifically, API versioning should occur any time you:

• Change fields or routing after an API is released.
• Change payload structures, such as changing a variable from an integer to float, for instance.
• Remove endpoints to fix design or poor implementation of HTTP.

If you need to change any of these after your API has already been released, it might be time to release a new API version. This way, the digital products of your existing customers won’t break or be disrupted.

There can be other reasons why you might want to create an API version, too — for example, adding endpoints or new parameters to responses could also call for a revision. These changes may not warrant a whole new release, though. A minor update would likely do. Regardless, keeping track of minor revisions could help troubleshoot a customer’s technical issues.

Making changes to an existing API means evolving the API contract. Before we delve into the different ways to create an API version, let’s consider the API contract for a moment.

What Is The API Contract?

The API contract is the agreement between the API producer and consumer. It details what the consumer can expect from the API in both a machine- and human-readable format. It’s a way to establish trust and accountability between the API producer and the consumer so that developers can build tools using that API with confidence.

An API contract is also a way to keep track of the changes made to an API. It then raises questions of what falls within the API contract scope and what doesn’t. Should an API contract define URIs? How about media types?

Let’s consider URIs first. Should URIs be covered by the API contract? According to Roy Fielding, this violates the dictum that APIs should be as hypertext-driven as possible. URIs are driven not by the API itself but by what Fielding considers “out-of-band information.” According to Fielding, a client should be able to operate an API with no additional information. Under this interpretation, URIs are not part of the API contract.

The types of media contained in the API are, though. A client needs to know what types of media are contained in an API to consume it properly. A REST API should include details about the types of media it contains, as clients need to know that information to use the API.

Changes to the API contract can often be mitigated with API versioning. This gives your existing users a chance to segue to the new version and sundown features and endpoints you’re phasing out.

Now let’s take a look at the more popular methods for API versioning.

3 Types Of API Versioning

The most common reason for API versioning is honoring contracts with your existing API customers. Their apps may rely upon the way your API functions when they set it up. Just because you need to update your API doesn’t mean they’re ready to do the same for their apps.

API versioning is a way to segue between releases smoothly. It’s the best way to sundown an asset or endpoint, as you can keep the deprecated features in older versions. You can also leave notes in your API documentation detailing your development schedule, which will help keep your consumers aware and make the necessary revisions.

There are multiple ways that you can create different versions of your API. Here are a few of the most common.

1. URI Versioning

The most common method of API versioning is to specify the API version in the URI itself. It’s the most common method because it’s also the most effective.

Consider the following hypothetical endpoint:

https://www.imaginaryapi.com/api/1/catalog

Easy, right? It only requires setting up API endpoints, which you’d be doing anyway. It also allows your clients to save assets if there’s ever an update.

It’s a solid method, but it also violates one of the dictums of good API design — that every URI should contain unique resources. It’s also easy for URI versioning to get out of hand, potentially leading to a large URI footprint.

URI versioning can also be very rigid and inflexible. It’s not possible to update a single resource or a smaller portion of the overall API. This means that URI versioning is all-or-nothing. Creating an entirely new version can be a daunting task, which can lead to slower production schedules.

Finally, URI versioning can cause issues with HTTP caching. An HTTP cache would have to store each version.

2. Query Parameter Versioning

A query parameter versioning approach is quite effective, as well. It lets you specify the API version as a query variable.

For example:

https://www.imaginaryapi.com/api/products?version=1

This approach is quite simple to implement as well. It also makes it easy to make the latest API version the default unless another version is specified.

3. Custom Headers

This method lets you specify the version by creating custom headers using version numbers.

For example:

Curl -H "accepts-versions: 1:

https://www.imaginaryapi.com/api/products

This way, no filler is added to the URI.

When Not To Version an API

As we’ve seen, API versioning can be a lot of work. It also raises the risk of breaking an API for your existing customers and API consumers. Sometimes it’s best to avoid creating a new API version if possible.

As a general rule of thumb, it’s best to avoid creating a whole new version unless you’re making changes that will break the API for your existing users.

For example, consider adding additional info to the user category:

{
    "user": {
        "name": "John Doe", 
        "amount": "100"
    }
}

This change would not break the API for your existing customers, so a new version would not be necessary.

Now consider this alternate example in which a new media type is specified:

===>
GET /users/3 HTTP/1.1
Accept: application/vnd.myname.v2+json
<===
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v2+json
{
    "user": {
        "firstname": "John", 
        "lastname": "Doe", 
        "amount": "100"
    }
}

This adds even more detail to an existing URI. It also could indicate a change that could break the API for existing users, as they’ll need to understand the new media type and the accompanying semantics. It doesn’t create the need for a whole new URI, though, meaning a completely new version may not be necessary.

Finally, even major structural changes may not necessarily indicate the need for API versioning. Changing the state of representation or mirroring a Resource requires a significant overhaul of how a client interacts with an API. It doesn’t necessarily need a new version, though. A new resource does not necessarily change the API further up in its structure.

Adding more information or variables to a URI is not ideal, but it also doesn’t mean an API isn’t adhering to RESTful principles.

Final Thoughts

As you can see, there’s a lot to ponder when creating a new API version. As with most things dealing with APIs, your approach will likely boil down to taste and your unique circumstances.

To summarize, we’ve taken a look at what an API version is. We’ve also talked about the API contract and what it does and does not cover. We’ve discussed the most common methods employed for API versioning. Finally, we’ve discussed some gray areas that may or may not call for creating a new API version.

Again, as a general rule of thumb, it’s best to avoid creating a whole new version if at all possible. This avoids the potential for breaking your API for your existing clients. It’s also preferable from an HTTP caching standpoint. You’d do better to add more data or fields into existing URIs, or you can even create versions of the media itself.

Thinking through these potential issues will help you to determine if API versioning is the right approach. It also helps you consider your existing customers to make sure that you uphold your agreements.