API Versioning Methods, a Brief Reference

This post lists the most common methods in use to version your API. Its intention is not to convince you to use one or another but rather to provide a comprehensive list of the methodologies used, together with some of their advantages and disadvantages and some additional references for each method as well.

Advantages and Disadvantages

Media Type Versioning

Also known as “content negotiation” or “accept header”.

You customize the accept media type header to specify the version: Accept: application/vnd.myapi.v2+json or Accept: Application/vnd.api.article+xml; version=1.0

PROS

• You can version directly at the resource level (preserve your URIs between versions).
• This is the closest to the original RESTful specification (check the references below).

CONS

• Harder to test as the versions are not shown on the URL.
• You will need something else than just a browser (i.e. developer tools) to explore the different versions.
• They distort the HTTP headers’ purpose: clients will need to know the media type for each resource and request the same one throughout their use of your API to ensure their code continues to function normally as you push out new changes.

(Custom) Headers Versioning

One of the most (mis)used methods — i.e. X-API-Version: 2.

PROS

• Preserve your URIs between versions (because you do not add any version information to the URI).
• Neater method than the URI versioning up next.

CONS

• If you are already versioning resources with this technique, versioning the API as well can lead to a hard-to-manage configuration.

URI Versioning

You will use a different path for different versions of the API endpoints. (i.e. api.example.com/v1/resource ).

PROS

• Most common method currently in use by APIs today.
• It allows exploring different versions with just a browser. (Enables visual identification of the version being requested).
• It’s easy to use!

CONS

• It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version).
• Just like the previous method you should try to avoid this method if you are also versioning resources.

Domain Versioning (AKA “Hostname Versioning”)

It’s a particular case of the URI versioning in the previous section, and it shares its pros and cons (i.e. apiv1.example.com/resource).

PROS

• Same as in URI versioning.
• Also easily route it to a completely different server.
• Could be interesting if you really want to write something very different for the same resources.

CONS

• Same as in URI versioning, plus users may have to change their security settings to be able to make calls to this new version.

(Request) Parameter Versioning

Use a parameter in the request to provide the API version being used (i.e. 

).

PROS

• This is mostly indicated for JavaScript API (CORS enabled APIs).
• Just like the URI versioning allows visual identification.
• Can be optional (if no parameter is specified, the last version will be provided).

CONS

• If you mix resource versions with this type of API versioning, it can get very messy.

Date Versioning (AKA “Point-in-Time Versioning,” “Dynamic Date Versioning”)

The first time a user makes a request to the API, that point-in-time (timestamp) gets saved alongside the account data and becomes their version until they choose to manually bump it to the current version

PROS

• Allows shipping new API features without changing an endpoint.
• Being able to easily see which customers are using which versions of the API

CONS

• It’s a bit complex to implement.
• Makes traceability of what has changed more difficult (It can be confusing to understand whether the timestamp is compilation time or the timestamp when the API was released).

Popularity

Another table that I thought might be interesting to share with you is this one below, with the estimated popularity — how often that method is used: high, medium and low usage frequencies — and some references for you to check out. The popularity is based on the listings of some popular REST APIs (you can find some of these listings on the next section of the post).

Media Type Versioning (AKA “Content Negotiation” or “Accept Header”)

Popularity: MEDIUM

References:

• GitHub has gone down this path.
• http://tools.ietf.org/html/rfc4288#section-3.2
• http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/
• http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_2
• http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/
• Foursquare: https://developer.foursquare.com/overview/versioning

(Custom) Headers Versioning

Popularity: MEDIUM

References:

• Microsoft uses this method: https://msdn.microsoft.com/en-us/library/azure/dd894041.aspx

URI versioning

Popularity: HIGH

References:

• Segment uses this approach: https://segment.com/docs/libraries/http/
• And Twitter too: https://blog.twitter.com/2013/api-v1-retirement-final-dates1

Domain versioning (a.k.a. “hostname versioning”)

Popularity: LOW

References:

• Facebook uses this method: https://developers.facebook.com/docs/marketing-api/versions

(Request) parameter versioning

Popularity: HIGH

References:

• Pivotal uses this: https://blog.pivotal.io/labs/labs/api-versioning

Date versioning (a.k.a. “point-in-time versioning”, “dynamic date versioning”)

Popularity: LOW

References:

• Clearbit (https://clearbit.com/docs#versioning),
• Runscope (http://blog.runscope.com/posts/managing-change-behind-the-scenes-with-continuous-regression-testing-for-a-seamless-customer-experience)
• And Twilio use this method.

References

Finally, lets wrap this blog post up with some generic, but equally interesting, references on the subject matter:

• https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
• http://urthen.github.io/2013/05/09/ways-to-version-your-api/
• http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
• http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/