Hey, I addressed this point in the blog post. I disagreed with that because a) its not self-documenting. b) On v2 the exact same URLs will have completely different data and probably break every API consumer.

Accept header based versioning is self-documenting. I've worked on implementing support for this in tastypie: https://github.com/toastdriven/django-tastypie/pull/394

It's like this:

--> GET /api/ Accept: application/json

<-- Content-type: application/vnd.api.v1+json <stuff>

Then your consumers can know what version of the API they're interacting with and act accordingly.

Without reading the docs at quite depth I think it would be easy to overlook the response content-type

What about the ability to look at API responses in a browser? You can't normally change the request headers a browser sends without some type of plugin.

Including the version number in the URL gets around this and even allows you to test API responses in mobile browsers if needed.

Although I tend to agree that a header-based approach is cleaner and more in the spirit of REST and even HTTP.

Well, I think the way you do it is provide examples of interaction that sends an explicit Accept with client interactions. Detecting Content-type and reacting accordingly is only for totally blind discovery.

That's also a pretty recent pull, and wasn't there the last time I saw Klabnik's post here on HN (a couple weeks ago).