What's the preferred option for API versioning?

Do you have it in the path like /api/v1? Or in the HTTP headers? Or any other way?

What are the pros and cons to this?

Write your answer…

6 answers

In my mind, one of the greatest benefits of RESTful APIs is the discoverability provided by the URI. To that end, I always prefer to put API version information in the URL itself. This dramatically reduced the amount of go-round between yourself and outside developers when troubleshooting any issues with the API, or their implementation on the client end. If API version is stored in headers, this is less clear and can lead to hidden issues.

Is this truly REST? Enh, you could argue not, that the URI pointing to the resource changes with the version. I find that letting the REST-at-all-costs mentality guide the design of my APIs only hinders the usability. Very few people actually design fully REST-compliant software, so we're all trying to find out which deviations improve upon the pattern in the real world. Mandatory versions in the URL, in my opinion, is one of the better deviations to make.

As always when discussion REST API design, I must plug this short and easy to read PDF by Apigee: https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf. This is some of the best advice you'll get on the subject, and it only takes about 30 minutes to read.


Hashnode is building a friendly and inclusive dev community. Come jump on the bandwagon!

  • 💬 A beginner friendly place

  • 🧠 Stay in the loop and grow your knowledge

  • 🍕 >500K developers share programming wisdom here

  • ❤️ Support the growing dev community!

Register ( 500k+ developers strong 👊)

We've been building a hypermedia API and are likely to implement versioning leveraging content negotiation via HTTP headers. Rob Zazueta of Mashery has a great piece on this titled "The Ultimate Solution to Versioning REST APIs: Content Negotiation", mashery.com/blog/ultimate-solution-versioni..

Another good piece on the different ways of versioning — and how no one really has a favorite — is Troy Hunt's article "Your API versioning is wrong, which is why I decided to do it 3 different wrong ways". troyhunt.com/2014/02/your-api-versioning-is..

We are building API's for our mobile applications and prefer keeping API version in url such as "app.com/v1/endpoint". This way we could keep running old applications(not updated by user) without any issue and pushing updates to appstores with new API url for new installs.

We are also following this method in our new API generation tool API Plug too. Our users could generate their API versions on fly and download all versions such as api/v1, api/v2 and upload to their servers.


Thank you. I did check out the API plug!

Reply to this…

A co-worker put me on to the chapter in "Architecting Composite Applications and Services with TIBCO", which is so old it talks about WSDL. Thankfully, the things it has to say about versioning is above and beyond any specific technology.

To look at the basics, it's usually easier to pattern match on the URL. So /API/foo1 and /API/foo2 tend to be easier to work with than getting the headers in the request, depending on your loadbalancers.

You could do /API/v1/foo, /API/v1/bar, but then when any call has a breaking change do all calls upgrade to v2? Or do you have per-call URI paths?

I prefer to version at the end of the endpoint name and not set the version inside the string, although people like Twilio think differently and probably have extremely good reasons (their version string is the date the API was released)

Something that I've found to be powerful is including the client version in the request headers. That way, a bug in the client can be dealt with by the interface or provider, rather than a forced client update.

Show all replies

The URL is certainly the easiest place to have it, I prefer using sub-domains v1.api.myapp.com/more/stuff/here, then any work on v2 of the api doesn't affect v1 at all, v1 and v2 would be completely different apps.

Reply to this…

Load more responses