What are the pros and cons to api versioning methods

Question

I've notice in some example two ways of versioning an api.

One of them is using a version in the url

/api/v1/products

The other is using the content type header and the accept header to mark the api version for the data send to the server

Content-Type=application/vnd.company.v2+xml

What are the pros and cons to this approaches ? What are some use case where you will use each approach ?

Answer 1

I've been used to having the version number in the URL itself (/v1/). I personally think this is a much cleaner approach - this way, the end user (or developer) doesn't need to handle HTTP headers, and can simply modify the REST API/call to access different versions of the API as needed.

I'm thinking that its also possible that some of the HTTP APIs out there in different languages may not have full support for HTTP headers, so you always make to make the API most readily available to the end user. Re-writing the URL is the simplest way, and it should work with anything that supports HTTP out there.

Finally, allowing the API version to be specified using the URL allows simple testing using a web browser. If you incorporate versioning into a HTTP header, the developer is forced to use a programming language to do testing.

Answer 2

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, the URL versioning approach is more widely used.

Here are the Pros and Cons that I could find (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.
7. When you put the version in the URL, your clients need to coordinate a change of their code (or if they're smart, their configuration), to the new API. Header Pro/URI Con.

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

• Martin Fowler's description of the Richardson Maturity Model
• API Versioning - Pivotal Labs
• HATEAOS
• Informit.com's Article on Versioning REST Services

Answer 3

Better to use version in URL. I was looking for this a while back and came across the following 2 resources which discuss RESTful API Design at length.

1. Best Practices for Designing a Pragmatic RESTful API - Version via the URL, not via headers.
2. programmers.stackexchange.com : What is a recommended pattern for REST endpoints planning for foresighted changes?

TL;DR Answer: Using Version # in the URL is a recommended approach.

Some of the most-well-designed-APIs ever that I've come across -- Instagram API and Stackoverflow.com API -- both use this approach to API versioning.