Take the 2-minute tour ×

Are there any known howtos or best practices for web service REST API versioning?

I have noticed that AWS does versioning by the URL of the endpoint. Is this the best way?

share|improve this question
I don't understand the notion of REST API versions. There really shouldn't be an 'API' version. Each resource can have its own media type and version. If correctly implemented, a client is oblivious to changes in resource versions as the server returns the URIs the client needs to follow as a media type the client can understand, due to the use of the Accept header. The server will always respond with a media type the client can handle or a 406 Not Acceptable. See answer stackoverflow.com/questions/972226/how-to-version-rest-uris/… which does a great job of explaining. –  dacamo76 Jul 5 '11 at 0:22
The AWS link is broken. I think docs.amazonwebservices.com/AmazonSimpleDB/latest/DeveloperGuide/… may be the new location. –  retracile Sep 19 '11 at 18:14
I am a little intrigued as to why there is not much discussion around the "Accept-Version" header strategy to versioning? Is URI versioning considered a better bet? I saw lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned which shows most of them use versions in URIs. Any specific reasons? The "Accept-Version" header seems a neat way to avoid polluting the REST URLs with versions. Any thoughts? –  Paddy Mar 6 at 6:48
Browser caching is the #1 reason to include a version in the URL. Sometimes the browser will stubbornly ignore all HTTP directives and continue to pull the data from the cache. And the only way to fix that is by changing up the URL. –  Todd Smith Mar 6 at 12:27
This question has a lot of links all over the interwebs, and it's a clearly popular question (though as the answers have borne out, it's not a good fit for Stack Overflow's format). However, it does not need a bajillion more answers. If you want to answer, find one of the answers that you can expand upon and edit it with more information. If you're really, really, really sure there should be another answer here that isn't already talked about, then let's have that discussion in the comments. –  George Stocker Mar 6 at 13:24
add comment

closed as primarily opinion-based by templatetypedef, amon, George Stocker Mar 6 at 13:22


7 Answers

up vote 438 down vote accepted

This is a good and a tricky question. The topic of URI design is at the same time the most prominent part of a REST API and, therefore, a potentially long-term commitment towards the users of that API.

Since evolution of an application and, to a lesser extent, its API is a fact of life and that it's even similar to the evolution of a seemingly complex product like a programming language, the URI design should have less natural constraints and it should be preserved over time. The longer the application's and API's lifespan, the greater the commitment to the users of the application and API. On the other hand, another fact of life is that it is hard to foresee all the resources and their aspects that would be consumed through the API. Luckily, it is not necessary to design the entire API which will be used until Apocalypse. It is sufficient to correctly define all the resource end-points and the addressing scheme of every resource and resource instance. Over time you may need to add new resources and new attributes to each particular resource, but the method that API users follow to access a particular resources should not change once a resource addressing scheme becomes public and therefore final. This method applies to HTTP verb semantics (e.g. PUT should always update/replace) and HTTP status codes that are supported in earlier API versions (they should continue to work so that API clients that have worked without human intervention should be able to continue to work like that).

Furthermore, since embedding of API version into the URI would disrupt the concept of hypermedia as the engine of application state (stated in Roy T. Fieldings PhD dissertation) by having a resource address/URI that would change over time, I would conclude that API versions should not be kept in resource URIs for a long time meaning that resource URIs that API users can depend on should be permalinks.

Sure, it is possible to embed API version in base URI but only for reasonable and restricted uses like debugging a API client that works with the the new API version. Such versioned APIs should be time-limited and available to limited groups of API users (like during closed betas) only. Otherwise, you commit yourself where you shouldn't.

A couple of thoughts regarding maintenance of API versions that have expiration date on them. All programming platforms/languages commonly used to implement web services (Java, .NET, PHP, Perl, Rails, etc.) allow easy binding of web service end-point(s) to a base URI. This way it's easy to gather and keep a collection of files/classes/methods separate across different API versions. From the API users POV, it's also easier to work with and bind to a particular API version when it's this obvious but only for limited time, i.e. during development.

From the API maintainer's POV, it's easier to maintain different API versions in parallel by using source control systems that predominantly work on files as the smallest unit of (source code) versioning.

However, with API versions clearly visible in URI there's a caveat. One might also object this approach since API history becomes visible/aparent in the URI design and therefore is prone to changes over time which goes against the guidelines of REST. I agree! The way to go around this reasonable objection, is to implement the latest API version under versionless API base URI. In this case, API client developers can choose to either:

  • develop against the latest one (committing themselves to maintain the application protecting it from eventual API changes that might break their badly designed API client).
  • bind to a specific version of the API (which becomes apparent) but only for a limited time

For example, if API v3.0 is the latest API version, the following two should be aliases (i.e. behave identically to all API requests):


In addition, API clients that still try to point to the old API should be informed to use the latest previous API version, if the API version they're using is obsolete or not supported anymore. So accessing any of the obsolete URIs like these:


should return any of the 30x HTTP status codes that indicate redirection that are used in conjunction with Location HTTP header that redirects to the appropriate version of resource URI which remain to be this one:


There are at least two redirection HTTP status codes that are appropriate for API versioning scenarios:

  • 301 Moved permanently indicating that the resource with a requested URI is moved permanently to another URI (which should be a resource instance permalink that does not contain API version info). This status code can be used to indicate an obsolete/unsupported API version, informing API client that a versioned resource URI been replaced by a resource permalink.
  • 302 Found indicating that the requested resource temporarily is located at another location, while requested URI may still supported. This status code may be useful when the version-less URIs are temporarily unavailable and that a request should be repeated using the redirection address (e.g. pointing to the URI with APi version embedded) and we want to tell clients to keep using it (i.e. the permalinks).
  • other scenarios can be found in Redirection 3xx chapter of HTTP 1.1 specification


share|improve this answer
Using a version number in the URL should not be considered a bad practice when the underlying implementation changes. "When the interface to a service changes in a non-backwards-compatible way, in reality an entirely new service has been created...From the client's perspective, a service is no more than an interface and some non-functional qualities...if the interface to a service changes in a non-backwards-compatible way, it no longer represents an instance of the original service, but is rather a completely new service." ibm.com/developerworks/webservices/library/ws-version –  benvolioT Jul 22 '10 at 16:09
Do you have any thoughts on adding a header with the version number so it can be checked by clients or developers ? –  webclimber Oct 18 '10 at 17:48
See also the use of an Accept header to indicate the version that the client expects: blog.steveklabnik.com/2011/07/03/… –  Weston Ruter Jul 5 '11 at 7:23
For the last part: I would say that an API that is obsolete and not supported anymore should return 410 Gone, as a redirect might indicate that the new location is compatible when it isn't. If the API is merely obsolete but still exists, a Warning HTTP Header on the Response might be an option. –  Michael Stum Oct 29 '11 at 6:13
How do you deal with clients that are already using the stable URL like shonzilla/api/customers/1234 and you want to upgrade to a new version? how can you force them add the V2 (the old one) to the URL? –  Dejel Apr 11 '13 at 7:47
show 8 more comments

The URL should NOT contain the versions. The version has nothing to do with "idea" of the resource you are requesting. You should try to think of the URL as being a path to the concept you would like - not how you want the item returned. The version dictates the representation of the object, not the concept of the object. As other posters have said, you should be specifying the format (including version) in the request header.

If you look at the full HTTP request for the URLs which have versions, it looks like this:


GET v3.0/customer/123 HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml
<customer version="3.0">
  <name>Neil Armstrong</name>

The header contains the line which contains the representation you are asking for ("Accept: application/xml"). That is where the version should go. Everyone seems to gloss over the fact that you may want the same thing in different formats and that the client should be able ask for what it wants. In the above example, the client is asking for ANY XML representation of the resource - not really the true representation of what it wants. The server could, in theory, return something completely unrelated to the request as long as it was XML and it would have to be parsed to realize it is wrong.

A better way is:


GET /customer/123 HTTP/1.1
Accept: application/vnd.company.myapp.customer-v3+xml

HTTP/1.1 200 OK
Content-Type: application/vnd.company.myapp-v3+xml
  <name>Neil Armstrong</name>

Further, lets say the clients think the XML is too verbose and now they want JSON instead. In the other examples you would have to have a new URL for the same customer, so you would end up with:


(or something similar). When in fact, every HTTP requests contains the format you are looking for:

GET /customer/123 HTTP/1.1
Accept: application/vnd.company.myapp.customer-v3+json

HTTP/1.1 200 OK
Content-Type: application/vnd.company.myapp-v3+json

  {"name":"Neil Armstrong"}

Using this method, you have much more freedom in design and are actually adhering to the original idea of REST. You can change versions without disrupting clients, or incrementally change clients as the APIs are changed. If you choose to stop supporting a representation, you can respond to the requests with HTTP status code or custom codes. The client can also verify the response is in the correct format, and validate the XML.

There are many other advantages and I discuss some of them here on my blog: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html

One last example to show how putting the version in the URL is bad. Lets say you want some piece of information inside the object, and you have versioned your various objects (customers are v3.0, orders are v2.0, and shipto object is v4.2). Here is the nasty URL you must supply in the client:

(Another reason why version in the URL sucks)
share|improve this answer
Handling independent data contract version and service contract versions in Accept header seems a messy as much as it is messy in the URL. Are there any other options ? Also if I have multiple endpoints (soap, rest), should this also be indicated in Accepts and let the routing service at the server end decide the direction to the correct endpoint OR is it acceptable to have the endpoint coded in the URL ? –  ideafountain Dec 13 '11 at 22:48
I can't agree with this, at least to the point of your last reason. This seems to be saying the different parts of the URI have different versions. But that's not the point of an API version. The point is to have ONE version for the ENTIRE resource. If you change versions, it's a different API resource. That's why it doesn't make sense to see company.com/api/v3.0/customer/123/v2.0/orders/4321 but rather company.com/api/v3.0/customer/123/orders/4321 You're not versioning any given part of the resource, you're versioning the resource as a whole. –  fool4jesus Jan 3 '13 at 22:09
Semmantically using version number in header seems better. But its far much more practical using the URL: less error prone, best debuged, readily seen by developers, easily modifiable in rest testing clients. –  dcerecedo May 23 '13 at 22:59
What fool4jesus said. Versioning the URI isn't versioning the response object (which you could version independently if you chose - using headers). Versioning the URI is versioning the whole URI structure. –  Caoilte Jun 5 '13 at 11:21
@Gili: Actually, you should no longer use -x as it's deprecated by RFC6648. –  Jonathan W Oct 1 '13 at 16:10
show 7 more comments

We found it practical and useful to put the version in the URL. It makes it easy to tell what you're using at a glance. We do alias /foo to /foo/(latest versions) for ease of use, shorter / cleaner URLs, etc, as the accepted answer suggests.

Keeping backwards compatibility forever is often cost-prohibitive and/or very difficult. We prefer to give advanced notice of deprecation, redirects like suggested here, docs, and other mechanisms.

share|improve this answer
add comment

I agree that versioning the resource representation better follows the REST approach...but, one big problem with custom MIME types (or MIME types that append a version parameter) is the poor support to write to Accept and Content-Type headers in HTML and JavaScript.

For example, it is not possible IMO to POST with the following headers in HTML5 forms, in order to create a resource:

Accept: application/vnd.company.myapp-v3+json
Content-Type: application/vnd.company.myapp-v3+json 

This is because the HTML5 enctype attribute is an enumeration, therefore anything other than the usual application/x-www-formurlencoded, multipart/form-data and text/plain are invalid.

...nor am I sure it is supported across all browsers in HTML4 (which has a more lax encytpe attribute, but would be a browser implementation issue as to whether the MIME type was forwarded)

Because of this I now feel the most appropriate way to version is via the URI, but I accept that it is not the 'correct' way.

share|improve this answer
Assuming the route where the versioning was defined in the headers, one could say that HTML forms that use native form submission would always use the latest version of the API since they would not be passing the specific version they want to adhere to. However, XHR requests do indeed allow you to change the accepts and read the content-type headers. So basic forms are really the only problem. –  Kyle Hayes May 10 '13 at 23:04
I'm not sure I agree that URI is most appropriate, but the fact that Content-Type doesn't work with forms is very important indeed. –  wprl Dec 20 '13 at 4:00
add comment

There are a few places you can do versioning in a REST API:

  1. As noted, in the URI. This can be tractable and even esthetically pleasing if redirects and the like are used well.

  2. In the Accepts: header, so the version is in the filetype. Like 'mp3' vs 'mp4'. This will also work, though IMO it works a bit less nicely than...

  3. In the resource itself. Many file formats have their version numbers embedded in them, typically in the header; this allows newer software to 'just work' by understanding all existing versions of the filetype while older software can punt if an unsupported (newer) version is specified. In the context of a REST API, it means that your URIs never have to change, just your response to the particular version of data you were handed.

I can see reasons to use all three approaches:

  1. if you like doing 'clean sweep' new APIs, or for major version changes where you want such an approach.
  2. if you want the client to know before it does a PUT/POST whether it's going to work or not.
  3. if it's okay if the client has to do its PUT/POST to find out if it's going to work.
share|improve this answer
add comment

Put your version in the URI. One version of an API will not always support the types from another, so the argument that resources are merely migrated from one version to another is just plain wrong. It's not the same as switching format from XML to JSON. The types may not exist, or they may have changed semantically.

Versions are part of the resource address. You're routing from one API to another. It's not RESTful to hide addressing in the header.

share|improve this answer
add comment

Versioning your REST API is analogous to the versioning of any other API. Minor changes can be done in place, major changes might require a whole new API. The easiest for you is to start from scratch every time, which is when putting the version in the URL makes most sense. If you want to make life easier for the client you try to maintain backwards compatibility, which you can do with deprecation (permanent redirect), resources in several versions etc. This is more fiddly and requires more effort. But it's also what REST encourages in "Cool URIs don't change".

In the end it's just like any other API design. Weigh effort against client convenience. Consider adopting semantic versioning for your API, which makes it clear for your clients how backwards compatible your new version is.

share|improve this answer
add comment

protected by Robert Levy Feb 24 at 21:06

