On Mon, 2010-04-05 at 11:33 -0700, David Lutterkort wrote:
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.
Yep, and your earlier "thinking about how browsers use HTML is very
instructive" point helps understand that
Some common idioms used in HTML (e.g. a simple GET URL which has side
effects) aren't in line with RESTful thinking, though
> 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
Same here
- 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)
Indeed, the client should be able to negotiate whichever content type it
prefers - e.g. YAML is probably easier for simple clients to handle than
XML
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.
Agree - documenting the content format is going to be important bit, and
a schema only gets you so far for that
Cheers,
Mark.