RESTful URLs for distinct versions of a resource

Question

I\'m having a real hard time conceptually understanding something proper concerning URLs for versioned resources.

Let\'s say I have an application that tracks recipes in

Answer 1

I just implemented this pattern late last year, and followed a combination of 2a and 2b:

2c) Nested resources with versions considered subsets
-- /recipes/ultimate-thing/versions/      -> List of available versions of Ultimate Thing
-- /recipes/ultimate-thing/versions/2     -> Version 2 of Ultimate Thing
-- /recipes/ultimate-thing/versions/latest-> Redirect to current working version of Ultimate Thing

Don't think of longer URI's as "subresources" or "attributes", as if a URI identifies a thing. It's much more natural to treat a URI as identifying data, and, since HTTP URI's are hierarchical, longer URI's refer to subsets of data. An item in a collection is data: a subset of all the data in the collection. An "attribute" of a "thing" is data: a subset of all the data about that thing. A "subresource" is data about a "thing" that does not exist independently of its parent, and therefore is a subset of all the data about the parent.

In your case, you don't have to perform too much mental judo to think of recipes/cherry-pie/ as all the data about what a cherry pie is and how to make one, rather than a specific version of the instructions. That includes identity info and other non-version-specific data, but also a link to versions/, and links to the history and funny videos where someone gets one in the face. The URI recipes/cherry-pie/versions/ is then the subset of all cherry pie data which is versioned; in general, it is nothing more than a collection of links to each URI of the form recipes/cherry-pie/versions/{version}/. I would also include in versions/ a documented link to recipes/cherry-pie/versions/latest/, which does a temporary redirect to recipes/cherry-pie/versions/182/ or whatever the latest version is.

This works very naturally for clients. Lots of people trip up on what they see as an explosion of resources, and think the poor client can't possibly keep up. But if you divide your resources along natural user workflow boundaries, you won't have a problem. Some clients will want to browse a set of recipes; some will drill down to a single recipe (regardless of version); some will drill down to want to know how many versions there are, which one is the latest, and will select from among them; some will drill down and retrieve a single version. If you want to show all the versions for a single recipe, or for all recipes, you're probably doing something wrong (in the rare case you're not, design another resource, like recipes/byname/pie/quickview, which collects all the data and caches it heavily).