I posted on this at my blog (http://technodolt.blogspot.com/), and
copy the post here.
I'd love comments either place.
I'm having a problem here, and I think my problem derives from the
that we are, in reality, using one noun and two verbs.
We are doing
RESTfully speaking, that reads to me like: "here is an updated
representation of the resource at /categories/create" - that doesn't
make much sense to me (explained below).
This has the PUT verb, the create verb, and the categories noun.
Shouldn't we re-work the whole concept to be something like:
GET /categories (get an index of categories)
PUT /categories (send a group of new categories)
hrm... this looks to me like "here is an updated representation of
the entire collection at /categories" - i.e. replacing the whole
collection. Then again, maybe the resource at /categories has
attributes which can be updated independent of its children so maybe
that's what it could mean. However, I've seen *many* people try to
do that as a way of doing bulk updates to a *subset* of the
collection which, IMHO, is wrong.
POST /categories (update several categories at the same time)
That should mean "create a new resource (a child) in the /categories
DELETE /categories (delete several categories at the same time)
Again, no. That means "delete the categories collection".
Here's my take (I put 'always' in quotes because this isn't dogma,
just starting principles):
PUT 'always' means "here's an updated representation of the resource"
POST 'always' means "create a new child of the resource"
DELETE 'always' means "delete the resource"
GET ... duh
But what's "the resource"?
/categories => a resource (that happens to be a 'collection')
/categories/123 => a resource (that happens to be a 'member')
/categories/new => strictly speaking, another resource - the empty
form you can fill in to POST a new category
/categories/123;edit => again, strictly speaking, another resource -
the form you can use to PUT the category
So, remember when I initially said that "PUT /categories/create"
makes no sense? It's because "/categories/create" isn't a resource
IMHO - it's more like RPC. Nothing wrong with that, just that it's
not quite REST.
In the end it looks to me like you're failing to see the distinction
between /categories and "a subset of resources under /categories".
Every situation is different but I'd *start* by treating a subset of
a collection as a different resource:
# order is significant
map.resource :selected_categories, :path_prefix => '/categories'
POST /categories/selected_categories #=> makes no sense, don't
implement update() in selected_categories_controller
When you find yourself wanting to add verbs, take a shot at adding a
Remember tho - ultimately this is all a matter of taste, style and
convention rather than 'rules'.