Consider a simple photo storage service as an API. Users can only interact with the API if they’ve got an account. Let’s say authorization happens over HTTP Basic.

Given that, would you use URIs like /photos and /photos/{id} (as a photo list and photo detail resource, respectively)? What’s weird about those URIs is that my /photos is a different list of photos than your /photos – in other words, the resource represented depends on the information in the Authorization header.

A few weeks ago, I sent the following in a email to a co-worker asking for input on designing REST APIs in Django. Since then, I’ve quoted myself a few times; I thought these thoughts would be worth a (slightly edited) public home.

I think the best way to dive in terms of mistakes to avoid. If you poke around you’ll find a couple-three different stabs at writing a generic REST API module for Django.

I’ll have more notes about CouchDB later tonight.

First, though, I want to step back and look at the big picture.

A few months ago, Bill de hÓra wrote that “a framework like Django or Rails is purpose-built for the Web” (as opposed to old-school tools that try to pretend the Web doesn’t exist – I’m looking at you, ASP). It doesn’t sound like much, but to me this is the best possible compliment Django could be given. We’ve tried incredibly hard to make sure that Django respects and follows the general principles of the Web.