On Fri, 2010-04-02 at 20:11 +0100, Eoghan Glynn wrote:
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).
Yes, that's an incredibly important point about REST: decoupling client
and server as much as possible.
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).
I like that a lot - the remaining question then is how do you describe
all those media types ? I would actually lean towards not specifying a
MIME/media type (that can be taken care of with content negotiation
between client and server, so that the client can, e.g., choose between
an XML and json representation) and document the request and response
with some sort of schema:
<link method="post" rel="reboot"
schema="http://rhev-api.example.com/reboot-action"
href="http://host.rhevm/vms/XXX/reboot"/>
Not sure what the right schema language is .. WADL ? Relax-NG for the
response, something free-form for the request ? Since the schema only
documents one representation (e.g., XML) it should be clear how to get
to the schema for another representation (in practice, only JSON)
Doing this for the entire API is a lot of work (and even more work to
keep in line with the implementation), so it'll only be worth it if
there are actually clients that pay attention to the schema - otherwise,
you might as well document it in plain old English as most of the REST
API's out there do today.
David