Ask HN: Version numbers in a REST API

I did the same research some months ago and didn't find "the" solution or answer to this question.

Linkdump from my bookmarks to this topic:

Discussion: http://blog.sonoasystems.com/detail/one_size_doesnt_fit_all_... http://stackoverflow.com/questions/389169/best-practices-for... http://stackoverflow.com/questions/2024600/rest-api-versioni... http://stackoverflow.com/questions/972226/how-to-version-res... http://stackoverflow.com/questions/278686/versioning-restful... http://stackoverflow.com/questions/1679322/web-services-api-... http://stackoverflow.com/questions/2101566/what-are-your-web... http://barelyenough.org/blog/2008/05/versioning-rest-web-ser...

Examples: http://docs.amazonwebservices.com/AWSEC2/latest/APIReference... http://atlas.resources.ca.gov/ArcGIS/SDK/REST/versioning.htm... http://groups.google.com/group/twitter-api-announce/browse_t...

Hope this helps a little bit.

  - you're developing a service would typically be a core part of your client's businesses
  - the API will almost certainly need be revised after you release it
  - even if you choose not to support deprecated versions, you will need to give your clients enough time to switch
  - that means that there will be periods where at least two versions of the API will be live
  - and both versions will need to be live on their final endpoints

https://api-v1.xxxy.com/clients/list

I believe its a little neater than /v1/clients/list, albeit a little less standard.

  X-protocol-version: 3

Since it's REST, clients shouldn't be hardcoding any URLs aside from the API root. Therefore, if you think a version is ugly, you can make the sub-URLs unversioned for now and version them later if needed.

This would always point to the latest API version: api.example.com/clients/1/posts

If you want a specific version you do this: api.example.com/v1/clients/1/posts

Since we're using ASP.Net MVC we could register a 'route' which points api.example.com/ to the API v1 code. Then when /v2 comes out we just point it to that and v1 is still available.

From an "academic" point of view, the versioning through http accept headers is considered the "best one".

I'm usually going with a path prefix as nearly everyone else does.

As you probably have a lot of API users that don't know and care about http accept headers (and their connection libraries usually don't either), it might be a lot of PITA to convince them doing it right.

So imho you can use the "academic" solution and hire some API Support stuff, teaching each customer the benefits and ways to access versioned resources — or just use the most obvious de-facto standard like /v1/posts/<id>.

That's why I use this compromise.

In Addition, the http accept header versioning allows you to version on each resource independently. This might be a good thing but usually the whole API changes and not only one resource (change as in incompatible change, not an addition of some attributes)

http://barelyenough.org/blog/2008/05/versioning-rest-web-ser...

Namespacing by version also is pretty "clean." Imagine updating your API in the future without the namespace. You'd have to implement the version in some difficult way (for the end developer) such as during authentication or as a request param or cookie or something ridiculous. This all adds complexity to the developers using the API. Its _much_ easier for a developer to just say "The prefix for all RESTful API calls is http://foobar.com/v1. No developer will say thats not clean.

So please, put a version number in your API, put it at the beginning, and put it in the "vX" format.

It doesn't add much value to give users a /v2/ to call, if it's not because that /v2/ will keep working independently of changes to the app. If it stops working some time because you're changing your app, you'll still have to inconvenience your users by pulling an old version out of production. On the other hand, there's no point in forcing users to upgrade to a "new" API, if the new API doesn't do anything the old one didn't.

No reason you couldn't just deprecate what will stop working on a method-by-method basis instead. If you pair it with application-keys, you'll know which users are using the methods you're about to deprecate and talk directly to them about transitioning away.

When something less radical changes, you can add new parameters and add new fields in the response just fine, without invalidating the old version - and if you can't, add a new method, e.g. /clients/list_with_invoices/ as the new version of list.

If you in the future decide to write the next version of your webservice using a different technology (e.g. going from python to node.js or whatever), you want your front-end server (e.g. nginx) to direct the traffic to the correct back-end without too much trouble.

Also, think about rolling-out backwards-incompatible changes otherwise. People want their apps to work immediately before you roll out the backwards-incompatible changes and immediately after. This means that for a period of time, you're going to have both up as they do the transition. (Your only other option is to say "at exactly 8:00 PST we're going to make the change. So deploy your changes that adapt to the change at exactly that time so you don't have downtime.) It's a lot cleaner to use versions and have them switch their urls from /v1/ to /v2/ whenever they feel like it. Otherwise, what are you going to do? You need api.yoursite.com to stay the old version so you don't break apps that haven't switched yet. So you'd have to do something ugly like have people switch to new.api.yoursite.com to get the newer version. Then, once you've disabled the old version and had api.yoursite.com, you have to get everyone to switch back to using api.yoursite.com because pretty soon, new.api.yoursite.com is going to be the following version. (Or you could make that version newer.api.yoursite.com, and then the next one newest.api.yoursite.com, and then you're really screwed when you need the next version.)

Basically, the cost of versioning your API is very low, and the potential headache of making backwards-incompatible changes without it is huge. Just do it.

GET /client

Accepts: application/vnd.clientlist.v1+json

And they would get back the version 1 client list response. If they want v2, etc, they can specify a different content type (clientlist.v2+json, etc). Also note, that putting verbs in your URIs is counterintuitive. The verb for a REST operation is the HTTP method (GET, POST, PUT, DELETE). The URI should simply represent the resource being retrieved. An argument can be made that the client list is the resource, but in reality listing things from a REST API is a first class concept and shouldn't need separate URIs. It's simply a request for a specific resource type without qualifying it by asking for a single instance of that resource. So, GET /client would return all clients (can add query parameters for pagination, etc), GET /client/834 would return a single client resource.

See also: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

In our case, we decided to go with the version number in the API (I don't think it matters if you use "1" or "v1"), because we wanted to be able to easily route requests to various API versions in the future (using load balancers). But it's more a matter of taste than a hard technical decision.

If there's no version... * If there request is plain html then deliver a human readable documentation page (that still has hyperlinks for discoverability. * If the request is asking for whatever your application type is, redirect to the current stable version.

If there's an older version requested: * If it's no big whup, keep the old version usable. Sometimes I do this by just keeping the old version of the resource code around, sometimes by updating it to translate between the old version and the latest stable version. * If you want to kill an old version, think about what appropriate in terms of 300 Multiple Choices, 301 Moved Permanently, or 410 Gone relative to your users.