I’m not sure how I missed this post by Jacob Kaplan-Moss, where he’s throwing the kind of REST question out there that has, in the past kept me thinking for hours:

It seems like URIs like /people/{my-uid}/photos and /people/{my-uid}/photos/{photo-id} are more “pure.” But now that’s weird because only one single user ever has access to a given URI (e.g only user #7 gets to access the entire space under /people/7). And the information in the URI is redundant with the information in the Authorization header.

http://www.jacobian.org/writing/rest-wankery-question/

Then things get really interesting in the comments, with links to two great posts (which I also missed):

The last constraint is incredibly simple, but nobody actually does it. It’s named Hypertext As The Engine Of Application State. I still haven’t decided how to pronounce the acronym, I always try to say “Hate ee ohs,” which sounds like a breakfast cereal. Anyway, let’s break this down. We’re using Hypertext, fine, that makes sense. But what’s it mean to be an engine? And application state?

…

Now, when I said ‘nobody’ does this, what I meant was ‘for APIs.’ This is exactly how the Web works. Think about it. You start off on the homepage. That’s the only URL you have to know. From there, a bunch of links point you towards each state that you can reach from there. People would consider it ludicrous if they had to remember a dozen URLs to navigate a website, so why do we expect the consumers of our APIs to do so as well?

Haters gonna HATEOAS

Finally, comes an elegant, much more RESTful solution to the API version dilemma:

You can simply define a new media type – sayapplication/vnd.mycompany.myapp-v2+xml – and associate new multi-email format with it. Clients can then request whichever format they want. Older clients don’t know the new media type so they get served the older single email format.

…

Newer clients do know the new media type so they can have access to the new functionality.

VERSIONING REST WEB SERVICES

All three of these posts/discussions are worth reading, but if you only read one, read Steve Klabnik’s HATEOAS post.