On 11/30/07, <b class="gmail_sendername">Jesse Vincent</b> <<a href="mailto:firstname.lastname@example.org">email@example.com</a>> wrote:<div><span class="gmail_quote"></span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
[I don't have an opinion on this. It'd be nice to know what other RESTy<br>apps do]</blockquote><div><br>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.
<br><br>Here are my sources:<br><ul><li>atomrest.pl - <a href="http://www.isolani.co.uk/projects/necho/rest/atomrest.txt">http://www.isolani.co.uk/projects/necho/rest/atomrest.txt</a></li><li>atom-api.py - <a href="http://diveintomark.org/public/2003/08/atom-api-20030825.py">
http://diveintomark.org/public/2003/08/atom-api-20030825.py</a></li><li>RT's REST - <a href="http://svn.bestpractical.com/cgi-bin/index.cgi/bps/browse/rt/branches/3.6-RELEASE/">http://svn.bestpractical.com/cgi-bin/index.cgi/bps/browse/rt/branches/3.6-RELEASE/
</a> (since I couldn't find any actual create or update points, this didn't actually help me)<br></li><li>Quickbase API (no source and documentation I'm not sure I can actually link to)</li><li>I tried to read Rails, but my understanding of Ruby stinks... so nevermind.
</li><li>XML.com: Show Me the Code (article) - <a href="http://www.xml.com/pub/a/2005/03/02/restful.html">http://www.xml.com/pub/a/2005/03/02/restful.html</a></li><li>The Atom API - <a href="http://www.atomenabled.org/developers/api/atom-api-spec.php">
http://www.atomenabled.org/developers/api/atom-api-spec.php</a><br></li></ul>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.
<br><br>The REST-Wiki (<a href="http://rest.blueoxen.net/cgi-bin/wiki.pl?HttpMethods">http://rest.blueoxen.net/cgi-bin/wiki.pl?HttpMethods</a>) 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.
</div><br></div>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.
<br><br>In summary, I've come up with these guidelines regarding the REST implementation:<br><ol><li>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.
<br></li><li>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).</li><li>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.)</li></ol>I like my original proposal, but as long as we clear out the Location header in most responses, I'm good.