Hacker News Reader

Comment by rix0r | Hacker News Reader

You can also negotiate the version number in the HTTP header:

  X-protocol-version: 3

That way you don't need to pollute the address space.

View on HN

Don't do that. Companies routinely introduce routers to load-balance service hosts, and some of their bright ideas include using "Service Appliances"; crap that strips headers.

I had to take packet snippers to XML appliances :-/

API versioning is a good thing, and the best way to choose a version is via a parameter. Don't ever ever try to to encode the version into the security token you return to the clients; someone did that for succinctness, so that you could choose a version once upon connection establishment. It was a nightmare to debug looking at the logs.

With API design, your good design decisions will be taken for granted, and your bad ones will me immortalized in a mountain carving. Try to model it after some existing API that offers a similar functionality, or use an extensible design like the SugarCRM SOAP API, or Zuora's SQL-like one.

Are there any other disadvantages of this approach other than the problem with "Service Appliances"? Many REST APIs rely on HTTP headers for other things - do "Service Appliances" only remove non-standard headers?

I think it is okay.

E.g. if you are programming GData client, it suggest you to add version info (i.e. GData-Version: X.0 ) in the request header.

http://code.google.com/intl/zh-TW/apis/gdata/docs/developers...

If you can imagine a stupid, pointless, wrong way to deal with network traffic, there is an appliance somewhere doing it.

I once saw a significant uptick in users being unable to use an AJAX application because a developer "fixed" the RPC stuff to sent Content-Type: application/json headers instead of claiming to be text/html.

Putting a version number in an arbitrary header or the URL requires a layer 7 load balancer whereas using a different hostname (v2.api.com) can be repointed with DNS.

Maybe, but what do I do if the header is missing? Use the latest version?

If I use the latest version it is likely developers will simple leave the header out since it "Just Works" without it.

Then when I make a breaking change to the latest API those applications will get screwed. Yes its mostly their fault -- but its my problem.

personally I would put the API version as an argument to the URL and I would make it a requirement. Most developers likes strict requirements, no developer likes surprises either.

/api/getstuff?v=1.1&arg1=x&arg2=y

If the version isn't there just return a useful error.

The only downside to this is that it's slightly more difficult to do analytics on the URL requests coming in.

The #1 danger to your API's usability is the half-assed implementation a 3rd-party will release to the public without your prompting or involvement. Don't let that happen. Take initiative and release libraries for as many languages and frameworks as you can, or risk the danger of being sabotaged by someone's indifference, or most likely incompetence.

You can't believe how many time I have had problems with an API just to discover the 3 year old client library was using some "sensible defaults" for required arguments.

If the header is missing you could return a 4xx response. You could document that the header is required or return a message in the response body indicating the cause of the 4xx.

If client missed the version information in their request, you can send the request to the earliest supported version of the API by default.

This is how Google handle it and I think it make sense. http://code.google.com/intl/zh-TW/apis/gdata/docs/developers...

Reply on news.ycombinator.com