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.
- Include the API version in the URL like http://services.digg.com/2.0/comment.bury
- Adding a custom request header. For example Azure services accept custom header
x-ms-version: 2014-02-14to determine which API version to choose when responding to a client in some situations. - Modifying the Accept header to include the version like
Accept: application/vnd.musicstore-v1+json
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.
- How are REST APIs versioned? - Lists how popular APIs do versioning.
- Versioning REST Web Services
- Nobody Understands REST or HTTP