Have you investigated how to make your API forward and backwards compatible, so that you can make changes to your API without affecting your current clients? Did you cry yourself to sleep shortly afterwards?

It’s really difficult to be confident about API compatibility because:

  • You are planning for an unknown future.
  • You are scared that you won’t be able to support unknown future changes.
  • You are not omniscient.
  • You are not a time-traveler.
  • There are many convincing arguments about how to handle change in your API.
  • All the convincing arguments conflict with each other.

A hierarchy displaying a variety of common API version approaches, including providing a version in a URL, using content-negotiation, or providing a version inside a content type.

Despite your lack of omniscience, you shouldn’t struggle with how to version your API. Yes, there are many options and no expert consensus. But you don’t have time to waste on figuring that out; you need a solution you can feel good about, so that you can get back to the product you’re building or the service you’re providing. Every minute you ponder API versioning is a minute that you’re not creating value for your customer.

You should take advantage of someone else’s hard work instead, by looking at successful businesses and their API practices. If an approach is widely used by successful businesses, we can make the assumptions that:

  • Individual organizations used their talent and evaluated the options, and settled on this approach.
  • There are no serious practical problems with this approach; if there were, the widespread use would’ve quickly uncovered the issues and caused a change in direction.
  • The popularity of this approach leads to client-side support being well understood and accepted.

So, here’s some popular APIs and how they do in-API version control:

Product Versioning Approach
Amazon AWS Internal resource; XML namespace
Dropbox URL, /1/ prefix
Facebook No versioning.
Foursquare URL, /v2/ prefix
GitHub No versioning.
Google URL, eg. /plus/v1/ prefix
Klout URL, /v2/ prefix
LinkedIn URL, /v1/ prefix
Salesforce URL, /services/data/v26.0/ prefix
SendGrid No versioning.
Stripe URL, /v1/ prefix
Sun Cloud API HTTP, X-Cloud-Client-Specification-Version & Accept headers
Twilio URL, /2010-04-01/ prefix
Twitter URL, /1.1/ prefix

Looking at this data, what conclusions can you draw?

  • Some very successful applications use API versions in their URLs.
  • Some very successful applications do something different.
  • Applications that use API versions in their URL do it as a prefix to the URL path, and they usually use small numbers.

My conclusion is that you should use URL prefixed API version (eg. api.example.com/v1/). It’s the approach used by Google and that makes it a solid choice. Also, don’t worry too much; it won’t make or break your API to use any scheme. Get back to work on the things that will make or break it.