How are REST APIs versioned?

Posted on March 12, 2012, Modified on September 15, 2014

I am currently working on a REST API, and the question was raised, how are, and how should, REST APIs be versioned? Here are the results of my research.

It seems that there are a number of people recommending using Content-Negotiation (the HTTP “Accept:” header) for API versioning. However, none of the big public REST APIs I have looked at seem to be using this approach. They almost exclusively put the API version number in the URI, with the odd exception using a custom HTTP header. I am at somewhat of a loss to explain this disconnect.

Versioning strategies in discussions

POST	VERSIONING
Stack Overflow 1	URI
Stack Overflow 2	Content Negotiation
blog post by Jeremy	Content Negotiation
ycombinator discussion	some opinions both ways
Stack Overflow 3	Content Negotiation
Stack Overflow 4	Content Negotiation
notmessenger blog post	URI (against all headers)
Peter Williams	Content Negotiation (strongly against URIs)
Apigee Blog post on API versioning	URI (some discussion)
Mark Nottingham REST versioning	Recommending essentially versionless extensibility with a HATEOS approach
Nick Berardi on REST versioning	URI
Restify	“Accept-Version” header
Tom Maguire on REST versioning	Content Negotiation
Nicholas Zakas on Rest Versioning	URI
Steve Klabnik on Rest Versioning	Content Negotiation + HATEOS
Luis Rei on Rest Versioning	Content Negotiation with (;version=1.0)
kohana forum discussion on REST versioning	Many Opinions
Troy Hunt on REST versioning	Accept Header but also support custom header and URL
Paul Gear REST versioning	Recommending essentially versionless extensibility with a HATEOS approach

Versioning strategies in popular REST APIs

API NAME	VERSIONING	EXAMPLE
Twillo	date in URI
Twitter	URI
Atlassian	URI
Google Search	URI
Github API	URI/Media Type in v3	Intention is to remove versioning in favour of hypermedia – current application/vnd.github.v3
Azure	Custom Header	x-ms-version: 2011-08-18
Facebook	URI/optional versioning	graph.facebook.com/v1.0/me
Bing Maps	URI
Google maps	unknown/strange
Netflix	URI parameter	http://api.netflix.com/catalog/titles/series/70023522?v=1.5
Salesforce	URI with version introspection	{ “label”:”Winter ’10” “version”:”20.0″, “url”:”/services/data/v20.0″, }
Google data API (youtube/spreadsheets/others)	URI parameter or custom header	“GData-Version: X.0″ or “v=X.0″
Flickr	No versioning?
Digg	URI	http://services.digg.com/2.0/comment.bury
Delicious	URI	https://api.del.icio.us/v1/posts/update
Last FM	URI	http://ws.audioscrobbler.com/2.0/
LinkedIn	URI	http://api.linkedin.com/v1/people/~/connections
Foursquare	URI	https://api.foursquare.com/v2/venues/40a55d80f964a52020f31ee3?oauth_token=XXX&v=YYYYMMDD
Freebase	URI	https://www.googleapis.com/freebase/v1/search?query=nirvana&indent=true
paypal	parameter	&VERSION=XX.0
Twitpic	URI	http://api.twitpic.com/2/upload.format
Etsy	URI	http://openapi.etsy.com/v2
Tropo	URI	https://api.tropo.com/1.0/sessions
Tumblr	URI	api.tumblr.com/v2/user/
openstreetmap	URI and response body	http://server/api/0.6/changeset/create
Ebay	URI (I think)	http://open.api.ebay.com/shopping?version=713
Reddit	No versioning?
Groupon	URI	http://api.groupon.com/v2/channels//deals{.json\|.xml}
Geonames
Wikipedia	no versioning I think?
Bitly	URI	https://api-ssl.bitly.com/v3/shorten
Disqus	URI	https://disqus.com/api/3.0/posts/remove.json
Yammer	URI	/api/v1
Drop Box	URI	https://api.dropbox.com/1/oauth/request_token
Amazon Simple Queue Service (Soap)	URI Parameter and WSDL URI	&Version=2011-10-01
Youtube data API versioning	URI	https://www.googleapis.com/youtube/v3

Versioning strategies in popular REST Libraries

LIBRARY NAME	VERSIONING	EXAMPLE
node-restify	semver versioning in an accept-Version header	accept-version: ~3
Jersey	description of how to do Accept: header versioning in Jersey	Accept: application/vnd.musicstore-v1+json

Share on Facebook
Click to share on Google+
Click to share on Twitter
Click to print
More

No related posts.

This entry was posted in Uncategorized by Tim Wood. Bookmark the permalink.

23 THOUGHTS ON “HOW ARE REST APIS VERSIONED?”

Larry on April 16, 2012 at 7:50 pm said:

The version of GitHub’s API that you link to is deprecated. The new version v3 does its versioning via content negotiation whereas the old one had it in the URI. The new approach is documented here: http://developer.github.com/v3/mime/

BTW, I found this very useful. Thanks!

Reply ↓
Pingback: How are REST APIs versioned? | Lexical Scope | nodeJS and Web APIs | Scoop.it
Pingback: How are REST APIs versioned? | Lexical Scope | Modern web development | Scoop.it
Pingback: How are REST APIs versioned?
John (@strife25) on November 15, 2012 at 2:57 pm said:

Great list! I’ve also found the following article to be useful for API versioning strategies: http://blog.apigee.com/detail/restful_api_design_tips_for_versioning/

Reply ↓
Pingback: REST Fundamentals | planetgeek.ch
Mizuki Oshiro on November 27, 2012 at 12:53 pm said:

This is usually due to header-mangling and stripping. Mobile ISPs, proxy servers, some regular ISPs – they actually strip out headers from HTTP requests. So while content negotiation is a principally sound and proper way to do it, the realities of the world we live in require putting the version in the URI.

Reply ↓
- Tim Woodon November 29, 2012 at 12:41 pm said:
  
  Do you think it also has anything to do with people wanting to browse REST services in an ordinary web browser? I wondered if the difficultly of configuring the content-negotiation in most web-browsers might contribute to this.
  
  Reply ↓
  - Ionuț Tiberiu Stanon May 17, 2013 at 1:22 pm said:
    
    Think about API requests from JS (end user browser).
    
    Reply ↓
    - Tim Woodon May 17, 2013 at 1:49 pm said:
      
      I’m not sure I follow you. Are you saying it is easier to do it one way or the other from JS?
      
      Reply ↓
Pingback: Revealing KijiREST: Resources | Kiji Community - Build Real-Time Scalable Data Applications on Apache HBase
abhishek on June 12, 2013 at 6:52 am said:

another reason why URI based versioning isnt right…

http://bit.ly/14Vr4jc

http://abhishek.pamecha.me/blogs/versioning-in-web-services/

Reply ↓
David Roncancio on June 21, 2013 at 5:13 pm said:

I think another reason is an implementation reason, because its easier and cleaner to have some web server work as a proxy to take /v1/ -> v1 service implementation instead of handling it in the service itself with a buch of ifs, like if(version==1) -> v1 of the service implementation

Reply ↓
Pingback: REST Fundamentals | bbv Blog
Owen Rubel on March 13, 2014 at 2:11 am said:

Dont get bogged down by purists. Do what is simple, scalable and practical. Just because it may not fit a spec doesn’t mean it’s not better for your needs or your clients needs. After all, the biggest API users are using URI after all and they serve MILLIONs a day

Reply ↓
Ricardo Ruiz López on March 17, 2014 at 12:36 pm said:

Hello!
When an API is obsoleted, what do you do normally when you want to block an older version? What mechanism do you use?
Thanks.

Reply ↓
- Fred Flintstoneon August 2, 2014 at 2:44 am said:
  
  you are talking about deprecation and you need to version both the api form and the api function; in other words, you need to do versioning on the api application as well as on the apiObject that establishes how the api request/response is handled for each related uri.
  
  Reply ↓
Pingback: Decoupling API Versions From Codebase Versions | Haddad’s Journal
Owen Rubel on June 25, 2014 at 3:30 am said:

Found out after much reading that there is a good reason not to do versioning in header. forwards will not send header information properly and so it will often get lost. This is why alot of people after evaluation have stayed with versioning in the URI

Reply ↓
- BeosFreakon May 15, 2015 at 1:24 pm said:
  
  If that is the case then the forward is not being performed correctly. You would lose authorization, language, media types, etc.. Version belongs in the accept header. i.e. I accept this media type and this version.
  
  Reply ↓
Pingback: El mekki anouar | API Versioning – Different Approaches to API Versioning (1)
Pingback: RESTful APIs | LibreNMS development blog
Pingback: Designer une API REST | OCTO talks !