[jifty-devel] Handling of responses to updates in REST

[Andrew Hanenkamp]

On 11/30/07, Jesse Vincent <jesse at bestpractical.com> wrote:
>
> [I don't have an opinion on this. It'd be nice to know what other RESTy
> apps do]


After looking around some, I cannot find any implementation appending a
Location header or any other HTTP header, except in the case of 201 Created
responses to POST actions that create new object. Even, then, I found at
least one implementation that does not even append a Location header in that
case. It just returns the data.

Here are my sources:

   - atomrest.pl -
   http://www.isolani.co.uk/projects/necho/rest/atomrest.txt
   - atom-api.py -
   http://diveintomark.org/public/2003/08/atom-api-20030825.py
   - RT's REST -
   http://svn.bestpractical.com/cgi-bin/index.cgi/bps/browse/rt/branches/3.6-RELEASE/(since
I couldn't find any actual create or update points, this didn't
   actually help me)
   - Quickbase API (no source and documentation I'm not sure I can
   actually link to)
   - I tried to read Rails, but my understanding of Ruby stinks... so
   nevermind.
   - XML.com: Show Me the Code (article) -
   http://www.xml.com/pub/a/2005/03/02/restful.html
   - The Atom API -
   http://www.atomenabled.org/developers/api/atom-api-spec.php

>From what I can read, it would seem that the emphasis is typically on
including links in the response content directly rather than fussing with
HTTP headers at all, except in the case of object creation. The Atom API,
for example, requires that the content of a 201 response be descriptive
enough that the client could make an immediate PUT at the given address to
make changes, but the Location: header itself seems to be a recommendation.

The REST-Wiki (http://rest.blueoxen.net/cgi-bin/wiki.pl?HttpMethods) pretty
much reiterates the statements in HTTP 1.1 RFC about the use of the Location
during a 201 Created response, but makes no mention of the Location header
under any other circumstance.

I can find no mention of the Content-Location header in any reference I've
seen that is REST-specific. Therefore, if we go for consistency with other
implementations, we don't ship a Location header unless the action used isa
Jifty::Action::Record::Create. In that case, return a 201 response with a
Location header referring to URI using the primary key. Or, we can leave the
Location: header out altogether. The focus should be on presenting as much
information in the response content itself as possible. In fact, I found one
reference (not listed above) that indicated that some or all versions of
Adobe ActionScript can't even read the headers because they aren't always
provided to the plugin in all browsers, so containing all the information in
the content seems to be the key thing.

In summary, I've come up with these guidelines regarding the REST
implementation:

   1. Make sure the response content gives enough information to be used
   to make additional GET or PUT requests regarding the same object after a
   create or update.
   2. If we create something, we SHOULD return 201 with a Location:
   header referring to it. But it's more important that we describe what's
   going on in the response (which we do).
   3. We need to avoid 200 responses with a Location: because that seems
   to be a hard-coded rewrite for Apache (in my experience) to rewrite the
   response as a 302 with a Location:, which does not mean the same thing as a
   200 response as far as REST clients are concerned. (Actually, 302 is a kind
   of an ambiguous response anyway since user agents don't actually tend to
   follow the spec when handling it, particularly since 302 can be used as a
   substitute for 302 for backward compatibility with HTTP 1.0 agents. A
   303 tends to be the preferred REST way of communicating "Look over there" in
   a response.)

I like my original proposal, but as long as we clear out the Location header
in most responses, I'm good.

Cheers,
Sterling
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.bestpractical.com/pipermail/jifty-devel/attachments/20071203/28a4bd3b/attachment.htm