Hacker News Reader

Comment by Qix | Hacker News Reader

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.

View on HN

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...

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.

Reply on news.ycombinator.com