Another take on Mark's likeness to RPC point, or what you might call the operation-orientated or action-orientated parts of the API ...

How about encoding the action in the query string of the URI we POST to in order to initiate that action.

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)

Or have I trodden on some forbidden lawns there, of which Mr Fielding wouldn't approve?

Cheers,
Eoghan

On 31 March 2010 17:38, Geert Jansen <gjansen@redhat.com> wrote:


That's right. If you think of the command queue as the collection and
the command as an object you add to it by POSTing it, then you could say
its RESTful. But i agree it's a bit of a stretch.

> I think both ways are fine, but I'm not convinced that either is really
> RESTful according to Fielding's view of the world. Maybe that doesn't
> matter, though?
>
> Eoghan had an interesting suggestion on irc. These control commands are
> essentially requests for the VM to transition state, so perhaps this
> makes more sense:
>
>    GET /vms/XXXX
>    <vm>
>      <id>XXXX</id>
>      <name>foo</id>
>      <state>RUNNING</state>
>
>    </vm>
>
>    PUT /vms/XXXX
>    <vm>
>      <state>SHUTDOWN</state>
>    </vm>
>
>    PUT /vms/XXXX
>    <vm>
>      <host>barfoo.devel.redhat.com</host>
>    </vm>
>
> However, things get sticky when you think about:
>
>    - A request to shutdown might be ignored - e.g. the user might
>      dismiss the shutdown dialog in the guest
>
>    - A request to reboot isn't really a state transition request unless
>      we explicitly make REBOOTING a state
>
>    - These requests might take a long time to complete, so it might make
>      sense to return 202 Accepted and allow the client to poll for
>      completion
>
>    - The requests might accept parameters that do not belong in the
>      representation of a VM itself

I thought about this approach as well, but concluded it would not work
for reasons similar to the ones you describe above. If you are
requesting a state change, say, from State "Running" to "Down", then
there's not enough information in that request to execute it. It may be
the client's intention to do a hard power-off, or a shutdown instead -
both would transition from "Up" to "Down". Also as you mention some of
these transitions have parameters that do not belong to the VM. For
example, "Down" to "Running" (i.e. Start-Vm) takes up to 11 arguments.

Regards,
--
Geert Jansen, Product Marketing Manager EMEA