Re:Ask HN: Version numbers in a REST API
by dan_manges on Saturday July 17, 2010 @10:20AM
(#1523808)
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?
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.
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...
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.