rhevm.api.VM+xml
Accept: ditto
<vm>
<name>foo</name>
...
</vm>
201 Created
Content-Type: application/vnd.org.redhat.rhevm.api.VM+xml
<vm>
<link method="get" rel="latest" href="http://host.rhevm/vms/XXXX"/>
<link method="post" rel="reboot" type="application/vnd.some.type.describing.reboot.params+xml" href="http://host.rhevm/vms/XXXX/reboot"/>
<name>foo</name>
<guid>XXXX</guid>
...
</vm>
Not
a million miles away from your enumeration of the available actions in
the response, but maybe making the expected types a bit more explicit
(where for example we might want to parameterize a reboot with some
sort of timeout or grace period).
Cheers,
EoghanOn 2 April 2010 01:49, David Lutterkort
<lutter@redhat.com> wrote:
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