[resending to the list]

Hi David,

Thanks for the feedback.

I had been chewing over Mark's earlier comment on the 'PUT /vms/XXXX' style for VM creation not being "hypertext driven". Now I struggle to decipher some of Fielding's more subtle prescriptions, but on this point I was tending towards reading this as not baking intimate knowledge of the URI structure into clients, but instead maintaining the primacy of the hypermedia types and in particular the linkedness of these types (to allow navigation from a single entry point).

So I was thinking along the lines of using something like the Atom link element in the response to fully describe the set of further transitions available to the client, roughly speaking something like:

POST /vms
Content-Type: application/vnd.org.redhat.
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,
Eoghan


On 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