Subject: #331: clarify that 201 doesn't require Location header fields

From: Julian Reschke <[email-masked]>
Date: Wed, 07 Mar 2012 14:27:15 +0100

Hi there.

 From the bug:

> "The newly created resource can be referenced by the URI(s) returned in the payload of the response, with the most specific URI for the resource given by a Location header field."
>
> Some people read this as a requirement to include "Location". At least for PUT->201 that's nonsense, however.

Proposed change:

7.2.2.  201 Created

    The request has been fulfilled and has resulted in a new resource
    being created.  The newly created resource can be referenced by the
    URI(s) returned in the payload of the response, with the most
    specific URI for the resource given by a Location header field.  For
    a PUT request, the URI of the newly created resource is the effective
    request URI, and thus the response does not need to carry any
    additional information.

    The response can include a payload containing a list of resource
    characteristics and location(s) from which the user or user agent can
    choose the one most appropriate.

    (...)

(<http://trac.tools.ietf.org/wg/httpbis/trac/attachment/ticket/331/331.diff>)

Feedback appreciated, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 8 Mar 2012 11:41:53 +1100

Maybe I'm nitpicking, but I'd like to see it be more general; i.e., other methods could, in theory, be defined to use 201 without a location (although I'd grant this is unlikely).

It's also a bit wordy, currently.

Suggest:

"""
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).
"""

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

---

From: Julian Reschke <[email-masked]>
Date: Fri, 09 Mar 2012 10:16:12 +0100

On 2012-03-08 01:41, Mark Nottingham wrote:
> ...

I like this better, but it makes another change (talking about multiple 
resources being created) that we haven't discussed before; I believe 
this should go into a separate issue...

Rephrased proposal:

7.2.2.  201 Created

    being created.

    The newly created resource is 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).

(<http://trac.tools.ietf.org/wg/httpbis/trac/attachment/ticket/331/331.2.diff>)

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 10 Mar 2012 13:34:00 +0100

On 2012-03-09 10:16, Julian Reschke wrote:
>> Maybe I'm nitpicking, but I'd like to see it be more general; i.e.,
>> other methods could, in theory, be defined to use 201 without a
>> location (although I'd grant this is unlikely).
>>
>> 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).
>> """
>> ...
>

Hearing no objections: <clarify that 201 doesn't require Location header 
fields>

I have also created 
<http://trac.tools.ietf.org/wg/httpbis/trac/ticket/347> to track the 
other issue (more than one resource being created).

Best regards, Julian