ISSUE: Returning metainformation on a 201 (Created) response

 This was discussed between Paul Leech, Dave Kristol, and myself in
Friday's teleconference.

PROBLEM: When doing a PUT on a resource that already exists, the server can
send back a 200 or a 204 response. The 204 response allows the server to
send back an updated etag and other entity information about the resource
that has been affected by the PUT operation. This allows the client to do
the next PUT using the If-Match precondition to ensure that edits are not
lost.

There were some discussion of whether the etag is the *only* piece of
information that the client doesn't know (not included in the request). The
feeling was that in general this can not be assumed as the operation may
trigger server side dependencies that the server wants to communicate back
to the client.

When doing a PUT for *the*first*time* the resource is created on the server
and a 201 response is sent back. The semantics of the 201 indicates that it
can include an entity body. In section 9.5 (although this is in the
description of POST), it is stated that 

If a resource has been created on the origin server, the response SHOULD be
201 (Created) and contain an entity which describes the status of the
request and refers to the new resource, and a Location header (see section
14.30).

Hence, the server can not send information back on a newly created resource
using 201 as it can when updating an existing resource using 204.

It was discussed whether anybody does include an entity in a 201 response
as it would be a challenge for the editor to deal with the response entity
(it would have to be displayed in a new window, for example).

Four solutions were discussed:

1) When receiving a 201 response, the client can issue a HEAD request to
get the updated information. However, the cost of this is one additional
RTT and it may lead to race conditions if another client comes in a does a
PUT between the first PUT and the follow-up HEAD request. This could cause
the client to apply inconsistent metainformation to its version of the
entity body.

2) Introduce a new status code which has the semantics of 204 except that
it can only be used when a resource has been created. The problem here is
that existing editors will not understand this code and will default to 200
which is will not indicate that a resource has been created.

3) Do not allow entity bodies in a 201 response and say that all
information included in the response is about the newly created resource.
The problem here is that we don't know if anyone already sends back entity
bodies in a 201 response.

4) Change the definition of 201 to distinguish between the case when there
is an entity body and when there isn't:

If the response does not contain an entity-body but includes new or updated
metainformation in the form of entity-headers, then these header fields
SHOULD be associated with the created requested variant. If an entity body
is present in the response then all entity header fields apply to that
entity body.

Any 201 response can contain an etag indicating the current value of the
entity tag for the created requested variant, see [14.19].


See [14.30] for use of the Location response header field in a 201 response.

The consensus among us, I believe, is to propose 4).

Comments?

Henrik
--
Henrik Frystyk Nielsen,
World Wide Web Consortium
http://www.w3.org/People/Frystyk

Received on Tuesday, 28 July 1998 11:35:54 UTC