On 09/16/2010 05:09 PM, Eoghan Glynn wrote:
So for the sake of comparison, what we currently model as:
POST /hosts/123/install
Content-Type: application/xml
<action>
<root_password>geronimo</root_password>
</action>
you're suggesting we change to:
POST /hosts/123/actions
Content-Type: application/xml
<action>
<command>approve</command>
<root_password>geronimo</root_password>
</action>
right?
Yes, that is my suggestion.
How would you characterize the increased RESTfulness of the latter?
Is
it the use of a common target URI as opposed to a per-action URI (i.e.
/hosts/123/actions as opposed to /hosts/123/install) that makes its seem
less RPC-oriented in your view? I guess I'm not convinced that the
latter is any less reminiscent of RPC than the former.
This was my thinking: REST is all about collections of resources. A
collection has zero or more resources in it. All those resources are of
the same type, and the collection name indicates the type of its
embedded resources. Expressed in natural language, the name of the
collection should be the plural of the type of the resources it contains.
Applying this to the "install" now: Multiple <action> resources do not
form an "install" collection. When I look at "install", I have no idea
what would be in it, since it's not even plural. Multiple <action>
resources instead nicely form an "actions" collection. And the other way
around, if I look at an "actions" collection, it's immediately clear
that it contains <action> resources.
An variant to this (which i don't like, but would be RESTful IMHO) is a
subcollection of "install_actions" where you post an
"<install_action>"
resource.
Now one advantage of the action-specific URI approach that we've
taken
is that the set of potential actions on a resource can be described
nicely in the entity representation, in the form of a set of per-action
links. Whereas in the alternate model, we would presumably have just a
single action link in the representation, so we'd need to come up with a
new way of representing the set of possible actions applicable to that
resource.
You can still have multiple <action> links:
<action rel="install" href="hosts/actions" />
<action rel="approve" href="hosts/actions" />
What this tells you is that in order to "install" a <host>, you need to
POST an <action> to "host/actions". The thing that is not expressed
here, and would need to be defined as a convention, is that an action
requires a "<command>" field. If you'd really like you could define a
DTD for <action> to express that (please dont :).
Regards,
Geert