On Wed, 2010-03-31 at 19:38 +0100, Eoghan Glynn wrote:
Something like:
POST /vms/XXXX?action=reboot
In this case the 202 Accepted response (assuming asynch) could include
a URI to be used subsequently to poll on the current status. A new
specialized REBOOTING state wouldn't necessarily be required, instead
it could just use the existing states with multiple transitions (e.g.
Up -> ShuttingDown -> Down -> StartingUp -> Up).
So we'd be keeping the primary resource identification (/vms/XXXX)
without stretching the point to an imaginary action URI
(e.g. /vms/XXXX/reboot)
Just for the record: the latter (i.e. /vms/XXXX/reboot) is what we are
using for Deltacloud. I'd be leery of overloading updating an object
with a heavyweight operation like 'reboot'.
If I understand Mr. Fielding right (and I can barely claim I do), it's
more important to make it explicit to clients what they can do than what
the actual URL structure of the API is. For example, if a
'GET /vms/my-good-one' returns something like
<vm name="my-good-one">
... basic attributes of the VM ...
<actions>
<action name="reboot"
href="/vms/my-good-one/reboot"/>
<action name="terminate"
href="/vms/my-good-one/terminate"/>
</actions>
</vm>
you've killed two birds with one stone: (1) clients do not need to have
any knowledge about how to get from the VM URL to the URL for a specific
action (they still need to know about valid parameters for each action)
(2) you are advertising to clients what actions are valid on a given VM,
i.e. they do not need to duplicate the logic that determines which
action can be performed on a given VM - as a corollary, you don't even
need to give them enough information to make that determination, e.g.
if, besides the VM's current state, there are permissions involved.
I find thinking about how browsers use HTML very instructive in thinking
about this stuff: a browser has no idea why certain forms show up on a
web page, nor what they mean. All they know is how to render the form,
and how to let the user interact with the form to eventually let them
post a request.
David