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.

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-versioning-res…

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-wrong…

We do a combination of path and data schema versioning. GET /v1/user will return a data schema object or document which itself contains a version. { "version": "1", "etc": { ... } } For caching we also use X-header tags too (cache busting is a pain).

The root of all evil is not how to do versioning, it's more about how to describe demand for a specific version of a resource or data.

Recently we've started to use raml.org/ but so far we have no experiences to share yet.

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.

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: pages.apigee.com/rs/apigee/images/api-design-eboo…. This is some of the best advice you'll get on the subject, and it only takes about 30 minutes to read.

Great article to help you decide which is best for your needs: troyhunt.com/2014/02/your-api-versioning-is-wrong…