On Wed, 2010-04-07 at 19:49 +0100, Eoghan Glynn wrote:
Nice work!
Just some random thoughts that occurred on reading through the docco,
while they're fresh in my mind ...
Thanks for the feedback Eoghan
For the "POST /vms" triggering VM creation, an alternative
pattern
would be to return the complete representation of the newly created VM
in the response entity-body. Obviously this would only really make
sense if there's some extra information to convey, over and above what
the client already knows ... I dunno, the initial memory usage or
something. The point being to save on an immediate dereference of the
Location header provided in the response.
Yep, I agree - the only reason I hadn't done it was laziness :-)
It will be useful is to obtain server-generated defaults like the unique
ID for the created entity
Fixed in git and the wiki now
It would also be a convenient place to encode the links to the
"action" URIs (to reboot, suspend, migrate, whatever) .
Yep, going to look into that next
Which segues nicely to the use of the Link header in the response to
the top-level GET, which is kinda cool as it avoids marshalling up an
entity-body. But it might be slightly inconsistent to use the Link
header in some cases, but then to revert to inline <link> elements
elsewhere in the API (e.g. in the per-VMs links within a collection of
VMs returned from a search).
I don't love it either, I just copied it from some of the RESTeasy
examples - it seems a little obscure to me, really
Perhaps doing both might make sense - include the URIs in the response
body and header?
I'll flesh out the action URIs thing a bit and that might help decide
I think you're right to use 204 for the DELETE response code, as
long
as there's no entity-body. Now there might I guess be a case in the
future where some sort of status would be returned, maybe an
indication as to which alternative VM any migrated processes ended up
on. In that case, the status should revert to 200 OK.
Yeah. I don't love the idea of the status code changing sometime in the
future, but I guess 2xx is "successful"
Would it be completely broken for us to return 200 from DELETE with an
empty response body?
BTW I don't think the {BASE} in the Request-URIs is really
needed, as
the relative URI form is more common AFAIK (with the {BASE} kinda
hidden in the Host header).
Hmm, yeah, hadn't thought of that
I guess I was just thinking that the client would be given a URI for the
app ({BASE}), query that for collection URIs and proceed from there
without every parsing the {BASE} URI or the collection URIs
Feel free to play around with how this is expressed in the docs, we can
probably do a lot better
Cheers,
Mark.