Re: i69: Clarify "Requested Variant" [was: New "200 OK" status codes, PATCH & PROPFIND]

On Tue, 5 Feb 2008, Stefan Eissing wrote:

>
> Am 05.02.2008 um 03:40 schrieb Mark Nottingham:
>> I don't think that does the trick. APP creates multiple resources and 
>> returns a 201 with a Location of the "Member entry URI", mentioning that 
>> other resources could have been created in the process.
>> 
>> So, a 201 can imply the creation of one or more resources; if the response 
>> contains metadata (e.g., Location, ETag), they are associated with the most 
>> important one, in the judgement of the server.
>
> When thinking about a good wording for this, I stumble into the tar pit of 
> defining "cause" and "effect" for a http application that is unknown. Trying 
> to sort this:
>
> - resource are created on a server all the time. Even a DELETE may create a 
> resource, e.g. a record of the action. A PUT on an existing resource may do 
> the same (implicit versioning in DeltaV). These actions however will not 
> result in a 201 response.
> - A 201 response is sent when the server wishes to inform the client that, as 
> a consequence and in direct relevance to the request, the Location resource 
> was created.
> - In this light a "201" dies *not* describe a side-effect but a server state 
> change that is in direct connection to the request, relevant for the client 
> to know in the context of the request and often even the *only* possible 
> success code for the request.
> - The term "side effect" in 9.1.2 in 2616 is problematic. It has caused many 
> myths about GET. A GET can have side-effects on the server (writing 
> access.log, updateing statistics pages). But none of these side effects 
> should be of relevance to the client, nor can they be expected, nor a are 
> they reproducable. There is no statistical correlation between a GET and the 
> resource changes on a server.

I agree that even a GET might have side effects, but no "direct" ones. By 
"direct" I mean relative only to the processing of the HTTP request by the 
resource. ie: doing a GET on a resource X may generate a log entry (and 
this log entry may be addressable), but it's a global server action not a 
resource one.

> - a 201 response informs the client that "a" resource has been created (maybe 
> more)
> - a Location header informs the client of the URI of this new resource (if 
> missing the URI is the one of the request???)

As the URIs should be in the entity of the response, the logic of 
!Location => request URI is wrong.

> - a ETag header on the response indicates the current value of the entity tag 
> for this requested variant (request uri or location)

How does an ETag sent with a 201 differs from one sent with a 200 and a 
Content-Location?

Here is a proposed rewrite (pending the ETag part)
<<<
    The request has been fulfilled and resulted in one or multiple
    resources being created. The newly created resource(s) can be
    referenced by the URI(s) returned in the entity of the response.
    If a single URI can be used to identify the most important resource,
    in the case of multiple resource created, or the most specific URI,
    in the case of a single resource, this URI SHOULD be given by
    a Location header field.

    The response SHOULD include an entity containing a list of resource
    characteristics and location(s) from which the user or user agent can
    choose the one most appropriate.  The entity format is specified by
    the media type given in the Content-Type header field.  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.

    @@TODO
    A 201 response MAY contain an ETag response header field indicating
    the current value of the entity tag for the requested variant just
    created, see Section 6.1 of [Part4].
>>>

-- 
Baroula que barouleras, au tiéu toujou t'entourneras.

         ~~Yves

Received on Tuesday, 5 February 2008 10:55:18 UTC