UserPreferences

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


CategoryProposals