Hi Geert,
What the the "Link" header you talk about below?
Actually this header seems to have been kinda deprecated.
Its defined in RFC 2068[1], but then in the newer version of HTTP/1.1 (RFC
2616[2]) the Link header is dismissed as being "not commonly implemented".
Which is probably another reason to prefer the style of inlining a <link>
element in the returned representation.
Not sure i follow you guys here :) {BASE} is definately needed
as you may be sharing the URI namespace with other HTTP servers
(e.g. co-hosting it with the RHEV-M web UI would be a common
deployment scenario).
Probably a confusion introduced by me assuming that {BASE} stood for
something like "http://the.host.running.rhevm:8080", whereas I guess you're
thinking more of a context path, something like "/mgmtapps/rhevmapi". Agreed
the latter is needed in the Request-URIs.
Cheers,
Eoghan
[1]
http://www.ietf.org/rfc/rfc2068.txt
[2]
http://www.ietf.org/rfc/rfc2616.txt
<
http://www.ietf.org/rfc/rfc2616.txt>
On 8 April 2010 10:46, Geert Jansen <gjansen(a)redhat.com> wrote:
On 04/08/2010 10:12 AM, Mark McLoughlin wrote:
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
>
According to RFC5023, in case you return an entity with a 201 CREATED
response, you also need to set the "Content-Location" header. The
"Location" header needs to be set always, even if you don't return a body.
Confusingly, Location is an absolute URI, while Content-Location can be
absolute or relative. What the the "Link" header you talk about below?
Haven't looked at the code so not sure if you're doing that.
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?
>
I think we should return a 204 NO CONTENT. It is the most correct response
code, and we should set the right precedent. There's no clients to the API
yet so let's make sure that when they arise they expect the correct return
code.
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
>
Not sure i follow you guys here :) {BASE} is definately needed as you may
be sharing the URI namespace with other HTTP servers (e.g. co-hosting it
with the RHEV-M web UI would be a common deployment scenario).
Regards,
--
Geert Jansen, Product Marketing Manager EMEA
Red Hat S.r.L. T: +39 348 1980079
Via Antonio da Recanate 1 E: gjansen(a)redhat.com
Milan 20124, Italy
Calculate your virtualization TCO at bit.ly/7CKhUm