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

From: Mark Nottingham <[email-masked]>
Date: Thu, 21 Jun 2012 13:20:47 +1000

<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?

--
Mark Nottingham   http://www.mnot.net/

---

From: Julian Reschke <[email-masked]>
Date: Thu, 21 Jun 2012 08:46:43 +0200

> 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…

Sounds good with s/mayshouldmust/MAYSHOULDMUST/ (I assume that was a 
copy/paste problem...)

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 21 Jun 2012 10:39:23 +0200

On 2012-06-21 08:46, Julian Reschke wrote:
>> Proposal is to replace
>> <https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p2-semantics.html#status.201>
>> with:
>>
>> ""
>> 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?
>
> ...

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

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 21 Jun 2012 22:38:40 +1000

Looks good to me.

On 21/06/2012, at 6:39 PM, Julian Reschke wrote:

> (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>
>

---

From: Julian Reschke <[email-masked]>
Date: Thu, 21 Jun 2012 14:53:50 +0200

> Looks good to me.

-> <http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1683>