http://www.intertwingly.net/wiki/pie/PaceResponseBodyToPostRequests
== Abstract ==
Describes how to use HTTP rather than adding unnecessary constraints.
== Status ==
Open (ThomasBroyer)
== Rationale ==
In response to a POST request, when the server creates a new resource
and respond with a 201 (Created) status code, it's still free (per
HTTP) to return whatever body it wants to: "thank you", some debugging
information, warnings, any representation of the created resource
(eventually using content negotiation), etc.
'''There's no technical reason to restrict the returned entity to be
the Atom Entry Document representation of the created resource.'''
HTTP defines a Content-Location header which identifies the actual
location of the returned entity.
On the other hand, it defines a Location header that should be present
in response to POST requests when a new resource has been created
(using a 201 (Created) status code).
It's pretty easy to understand that if Content-Location and Location
values are equals, it means that the returned entity (identified by
the URL in the Content-Location header) is the one that has been
created (identified by the URL in the Location header).
Conclusion: as we've demonstrated above that there's no reason to
force an Atom Entry Document entity in the response to be a
representation of the one that has been created, '''there's no need to
define a constraint such as "if the response body is an Atom Entry
Document, it SHOULD come with a Content-Location header".'''
To makes things simple for client implementations, without adding any
burden in the client-side, '''let's just a very small constraint: if
servers want clients to consider Location and Content-Location equals,
they should send the exact same value, character-by-character.'''
== Proposal ==
In section 8.1 of draft-atom-protocol-09, replace the paragraph that reads:
{{{
When the server generates a response with a status code of 201 ("Created"),
it SHOULD also return a response body, which, if provided, MUST be an Atom
Entry Document representing the newly-created resource. Clients MUST NOT
assume that an Atom Entry returned is a full representation of the member
resource.
}}}
with the following:
{{{
As clients are likely to issue a GET to the URI given in the Location header
of 201 ("Created") responses, to retrieve at least some basic information
such the entry's atom:id, a server might want to return the entry in the
body of the response. Per [HTTP/1.1], to unambiguously tell the client that
the response body is a representation of the resource identified by the
URI in the Location header, the server has to include a Content-Location
header with the same value. To remove any ambiguity with respect to URI
normalization and comparison, this specification allows clients to
OPTIONALLY compare Location and Content-Location values character by
character. Even in the presence of such a Content-Location header (with the
same value as the Location response header), clients MUST NOT assume that
the response body is an Atom Entry Document, as content negotiation might
have been used. If the response body is an Atom Entry Document, clients
MUST NOT assume that it is a full representation of the member resource or
the exact same representation that could be retrieved at the URI given in
the Location header.
}}}
and remove the paragraph that reads:
{{{
When the POST request contains an Atom Entry Document, the response from
the server SHOULD contain a Content-Location header that contains the same
character-by-character value as the Location header.
}}}
== Impacts ==
By adding less constraints and be closer to HTTP "basics", the
protocol becomes more extensible and accounts for both evolutions of
both the protocol and HTTP.
== Notes ==
--
Thomas Broyer
