{"id":241,"date":"2012-03-12T17:17:56","date_gmt":"2012-03-12T17:17:56","guid":{"rendered":"http:\/\/www.lexicalscope.com\/blog\/?p=241"},"modified":"2014-09-15T08:48:07","modified_gmt":"2014-09-15T08:48:07","slug":"how-are-rest-apis-versioned","status":"publish","type":"post","link":"https:\/\/www.lexicalscope.com\/blog\/2012\/03\/12\/how-are-rest-apis-versioned\/","title":{"rendered":"How are REST APIs versioned?"},"content":{"rendered":"

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.<\/p>\n

It seems that there are a number of people recommending using Content-Negotiation (the HTTP “Accept:” header) for API versioning. However, none<\/em> 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.<\/p>\n

Versioning strategies in discussions<\/h2>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Post<\/th>\nVersioning<\/th>\n<\/tr>\n
Stack Overflow 1<\/a><\/td>\nURI<\/td>\n<\/tr>\n
Stack Overflow 2<\/a><\/td>\nContent Negotiation<\/td>\n<\/tr>\n
blog post by Jeremy<\/a><\/td>\nContent Negotiation<\/td>\n<\/tr>\n
ycombinator discussion<\/a><\/td>\nsome opinions both ways<\/td>\n<\/tr>\n
Stack Overflow 3<\/a><\/td>\nContent Negotiation<\/td>\n<\/tr>\n
Stack Overflow 4<\/a><\/td>\nContent Negotiation<\/td>\n<\/tr>\n
notmessenger blog post<\/a><\/td>\nURI (against all headers)<\/td>\n<\/tr>\n
Peter Williams<\/a><\/td>\nContent Negotiation (strongly against URIs)<\/td>\n<\/td>\n<\/tr>\n
Apigee Blog post on API versioning<\/a><\/td>\nURI (some discussion)<\/td>\n<\/tr>\n
Mark Nottingham REST versioning<\/a><\/td>\nRecommending essentially versionless extensibility with a HATEOS approach<\/td>\n<\/tr>\n
Nick Berardi on REST versioning<\/a><\/td>\nURI<\/td>\n<\/tr>\n
Restify<\/a><\/td>\n“Accept-Version” header<\/td>\n<\/tr>\n
Tom Maguire on REST versioning<\/a><\/td>\nContent Negotiation<\/td>\n<\/tr>\n
Nicholas Zakas on Rest Versioning<\/a><\/td>\nURI<\/td>\n<\/tr>\n
Steve Klabnik on Rest Versioning<\/a><\/td>\nContent Negotiation + HATEOS<\/td>\n<\/tr>\n
Luis Rei on Rest Versioning<\/a><\/td>\nContent Negotiation with (;version=1.0)<\/td>\n<\/tr>\n
kohana forum discussion on REST versioning<\/a><\/td>\nMany Opinions<\/td>\n<\/tr>\n
Troy Hunt on REST versioning<\/a><\/td>\nAccept Header but also support custom header and URL<\/a><\/td>\n<\/tr>\n
Paul Gear REST versioning<\/a><\/td>\nRecommending essentially versionless extensibility with a HATEOS approach<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

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

Versioning strategies in popular REST Libraries<\/h2>\n\n\n\n\n\n
Library Name<\/th>\nVersioning<\/th>\nExample<\/th>\n<\/tr>\n
node-restify<\/a><\/td>\nsemver<\/a> versioning in an accept-Version header<\/td>\naccept-version: ~3<\/td>\n<\/tr>\n
Jersey<\/a><\/td>\ndescription of how to do Accept: header versioning in Jersey<\/td>\nAccept: application\/vnd.musicstore-v1+json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"excerpt":{"rendered":"

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 … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[1],"tags":[],"class_list":["post-241","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p2e3P7-3T","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/posts\/241","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/comments?post=241"}],"version-history":[{"count":10,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/posts\/241\/revisions"}],"predecessor-version":[{"id":5921,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/posts\/241\/revisions\/5921"}],"wp:attachment":[{"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/media?parent=241"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/categories?post=241"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.lexicalscope.com\/blog\/wp-json\/wp\/v2\/tags?post=241"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}