35

I am planning to write a RESTful API and I am clueless how to handle versioning. I have read many discussions and blog articles, which suggest to use the accept header for versioning.

But then I found following website listening popular REST APIs and their versioning method and most of them using the URL for versioning. Why?

Why are most people saying: "Don't use the URL, but use the accept header", but popular APIs using URL?

Georg Leber
  • 3,470
  • 5
  • 40
  • 63
  • 1
    http://stackoverflow.com/questions/389169/best-practices-for-api-versioning – Kevin Panko Sep 19 '13 at 21:40
  • 1
    It's just two different approaches, you can't make a mistake when you use the URL, further, there is no "default" which might be confusing. – Nir Alfasi Sep 19 '13 at 21:40
  • 3
    As a developer, what way do you think it is easier to implement? If you were the client, what version would you consider simpler to consume? – acdcjunior Sep 19 '13 at 21:40
  • One reason not to use headers is if you have browsers as clients and need to use JSONP or CORS for cross domain/protocol calls. Specifying headers is not possible with JSONP and is not possible with CORS on some browsers (e.g. IE8). – theon Sep 19 '13 at 21:47
  • In my experience, for the clients, one way is not much different from another, the changes needed to make the code use a specific version (changing the URL vs. header) are small in both options (if you really push me, I'd even give a slight advantage to the URL option, as it communicates more clearly what version it is). – acdcjunior Sep 19 '13 at 21:48
  • As a developer, though, uh... again, in my experience, deploying a different version to a different URL is just so much, so much simpler. To handle multiple versions depending on just a header, you'd have do at least deploy a third service (probably invisible to the client, but nevertheless, YOU'd have to code it), just to dispatch the requests. So, if you can avoid all this fuzz, why go for it? – acdcjunior Sep 19 '13 at 21:50

1 Answers1

49

Both mechanisms are valid. You need to know your consumer to know which path to follow. In general, working with enterprises and academically-minded folks tends to point developers towards Resource Header versioning. However, if your clients are smaller businesses, then URL versioning approach is more widely used.

The Pros and Cons (I'm sure there are more, and some of the Cons have work-arounds not mentioned here)

  1. It's more explorable. For most requests you can just use a browser, whereas, the Resource Header implementation requires a more programatic approach to testing. However, because not all HTTP requests are explorable, for example, POST requests, you should use a Rest Client plugin like Postman or Paw. URI Pro/Header Con

  2. With a URI-versioned API, resource identification and the resource’s representation is munged together. This violates the basic principles of REST; one resource should be identified by one and only one endpoint. In this regard, the Resource Header versioning choice is more academically idealistic. Header Pro/URI Con.

  3. A URI-versioned API is less error prone and more familiar to the client developers. Versioning by URL allows the developer to figure out the version of a service at a glance. f the client developer forgets to include a resource version in the header, you have to decide if they should be directed to the latest version (which can cause errors when incrementing the version) or a 301 (Moved Permanatly) error. Either way there is more confusion for your more novice client developers. URI Pro/Header Con
  4. URI versioning lends itself to hosing multiple versions in the same application. In this case you do not have to further development your framework. Note: If you do this your directory structure will most likely contain a substantial amount of duplicate code in the v2 directory. Also, deploying updates requires a system restart - Thus this technique should be avoided if possible. URI Pro/Header Con.
  5. It is easier to add versioning to the HTTP Headers for an existing project that didn't already have versioning in mind from it's inception. Header Pro/URI Con.
  6. According to the RMM Level 3 REST Principle: Hypermedia Controls, you should use the HTTP Accept and Content-Type headers to handle versioning of data as well as describing data. Header Pro/URI Con.

Here are some helpful links if you want to do some further reading:

James
  • 11,654
  • 6
  • 52
  • 81
cosbor11
  • 14,709
  • 10
  • 54
  • 69
  • 12
    In short, header option has no practical pro :) – Halil Özgür Dec 04 '15 at 17:13
  • 4
    I'm reading but can't understand how point 4 is Header Con ???? Would you like to host 3 versions of your app??????? And if you already are serving from 5 servers would you really like to manage 15 JVMS??????????????????????? At least split 4 into 2 and make one FOR Header and the other against. – EralpB Jan 10 '17 at 09:30
  • 12
    You could add this: 7. Caching. URI-based versioning is intrinsicly cache-friendly. Header-based versioning requires extra care to be cache-friendly. *URI Pro/Header Con* – Christian Hujer Feb 19 '19 at 11:21
  • 4
    Two more... 8. If you want to route requests of different versions to different places, it's often easier for proxies/routers to do this based on URL path info than HTTP header info. URI Pro/Header Con; And 9. If you're big on HATEOAS, then with URI versioning, any linking resources must be versioned in lockstep with their linked resources, else you will break consumers when you change a link's URL to a new breaking version. Header Pro/URI Con. – johnr Sep 11 '20 at 21:38