The Right Way to Version Your API

There isn’t one. But here are a few options.

Versioning in the URI Path


Essentially the version number v2 is embedded in the path of the URI itself. Old API versions at the v2 namespace remain unchanged so as to not break existing clients, and new API features will live at v3, v4, and so forth.

The most common API versioning pattern, this pattern allows you to make drastic changes to future versions while leaving old APIs as is for backward compatibility.

However, it does mean having separate implementations for each version. Consumers of your API will also need to change their client code when switching between versions.

Versioning with a URI Parameter


Version is embedded in the query parameter v.

With this pattern, API consumers uses the latest version of the API when the options v parameter is omitted. However, changes may surprise users who don’t explicitly specify a version number.

Versioning with Content Negotiation

Github Content Type:application/vnd.github.1.param+json

The Content Type in the Accepts header contains a custom MIME type such as Accept:application/vnd.myapp.v1.user that is used to indicate the API version.

Defined in the HTTP/1.1 Standard, section 14.1, the Accept: header lists the MIME Types of the media that the agent is willing to process.

The benefit is it gives us finer grained versioning to different resources of your API. You can with this approach, return different resource representations on different versions. To a certain extent, we also save some URI changes for your API consumers. However, we do have the added complexity of having to add headers.

Versioning with Request Headers

Azure x-ms-version:2011-08-18

The API version is specified in a custom Request Header such as X-API-Version.

This separates versioning from API call signatures, and it’s not tied to specific resource versions.

In Closing

Versioning with URI components tend to be easier and is more commonly seen. Recently, more and more APIs are going with Versioning with Content Negotiation and Custom Headers.

Ultimately, you should pick an approach that fits your team and consumers best. Complex versioning gives you more granularity, but is more involved for API consumers/developers.

Regardless of your specific needs and versioning choice, it’s important to start versioning your API from the first public release of your API. You don’t want to break existing clients once your API is already released, to the frustration of your consumers.