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(a)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