Re: #347: clarify that 201 can imply *multiple* resources were created

On 2012-06-21 08:46, Julian Reschke wrote:
> On 2012-06-21 05:20, Mark Nottingham wrote:
>> <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/347>
>>
>> Proposal is to replace
>> <https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p2-semantics.html#status.201>
>> with:
>>
>> ""
>> The request has been fulfilled and has resulted in one or more new
>> resources being created.
>>
>> Newly created resources are typically linked to from the response
>> payload, with the most relevant URI also being carried in the Location
>> header field. If the newly created resource's URI is the same as the
>> Effective Request URI, this information can be omitted (e.g., in the
>> case of a response to a PUT request).
>>
>> The origin server must create the resource(s) before returning the 201
>> status code. If the action cannot be carried out immediately, the
>> server should respond with 202 (Accepted) response instead.
>>
>> A 201 response may contain an ETag response header field indicating
>> the current value of the entity-tag for the representation of the
>> resource identified by the Location header (see Section 2.3 of [Part4]).
>> """
>>
>> Comments?
>
> Sounds good with s/mayshouldmust/MAYSHOULDMUST/ (I assume that was a
> copy/paste problem...)
> ...

Full text:

4.4.2.  201 Created

    The request has been fulfilled and has resulted in one or more new
    resources being created.

    The newly created resources are typically linked to from the response
    payload, with the most relevant URI also being carried in the
    Location header field.  If the newly created resource's URI is the
    same as the Effective Request URI, this information can be omitted
    (e.g., in the case of a response to a PUT request).

    The origin server MUST create the resource(s) before returning the
    201 status code.  If the action cannot be carried out immediately,
    the server SHOULD respond with 202 (Accepted) response instead.

    A 201 response MAY contain an ETag response header field indicating
    the current value of the entity-tag for the representation of the
    resource identified by the Location header field or, in case the
    Location header field was omitted, by the Effective Request URI (see
    Section 2.3 of [Part4]).

(note that the last paragraph needed tuning so the PUT->201 special case 
is handled as well).

-> 
<http://trac.tools.ietf.org/wg/httpbis/trac/attachment/ticket/347/347.diff>

Feedback appreciated, Julian

Received on Thursday, 21 June 2012 08:40:06 UTC