Versioning REST APIs

Yesterday, a discussion happened around versioning REST APIs resulted in an interesting sequence of events where one person even started to attack my self and one other person via personally e-mails. So I wanted to explore more about versioning REST APIs to understand the problem and solutions better. Lets start by looking at why versioning is needed.

As Troy Hunt discussed in his popular post on API versioning, the main reason is evolution of software. Its hard (may be even impossible) to get software right in the first release. As world moves on, new requirements may come. So introducing a new version is unavoidable.

When your API get used by various clients, you may have to maintain multiple versions. It’s not realistic to expect that everyone will migrate to new version within short time period.

There are multiple popular ways to version a REST API and there are proponents and opponents for each of these solutions.

People have different views about above mentioned solutions. Some people argue that, you should always keep the resource URL as a constant. Then people argues that adding customer header sucks because it’s not the ideal way (semantically) to describe a resource. People says Accept header sucks because it is harder to test. You can no longer give a clickable URL to test the API. But as Troy has already discussed in his article there is no right and wrong way. You should go for the most practical solution for your situation.

If you are interested in this topic, you should read Troy’s post. And there are some other interesting posts as well.


Now read this

Web Application Development in Clojure

I did some coding in Scheme and Ruby last couple of months and felt that writing Java code is not fun anymore. But Java as a platform is really good for most of the tasks and I started to learn some Clojure because there is support for... Continue →