django-rest-framework: api versioning

Question

so googling around it appears that the general consensus is that embedding version numbers in REST URIs is a bad practice and a bad idea.

even on SO there are strong

Answer 1

One way of doing this is to have the versioning specified as part of the media type.

This is what GitHub currently do for their API.

You can also include media type parameters in your accept headers, eg Accept: application/json; version=beta, which will successfully match against JSONRenderer. You can then code your view to behave differently depending on the accepted media type, see here.

There's lots of different patterns for versioning in APIs, and I wouldn't say there's any great consensus around the right approach yet, but that'd be one reasonable possibility.

---

Update Jan 2015: Better versioning support will be incoming in the 3.1.0 release. See [this pull request]

Update March 2015: Docs for the versioning API are now available.

(https://github.com/tomchristie/django-rest-framework/pull/2285) for more details.