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

From: Henrik Nordström <[email-masked]>
Date: Tue, 05 Feb 2008 15:20:09 +0100

tis 2008-02-05 klockan 13:52 +0100 skrev Julian Reschke:

> Again? Why would you want to return a Location header in PUT->201? I 
> don't think servers do return it today.

Can think of a number of reasons. Location in 201 is pretty much the
same as Content-Location in 200. In simple cases it's identical to the
Request-URI but there is a number of cases where they may differ.

A example for PUT would be a server implementing "nameless PUT" to a
directory automatically assigning a name to the created resource.
Another would be when the PUT request was carried out on a valid URI for
the resource but it's not the preffered URI for fetching the created
resource, or yet another would be a versioned resource where each PUT
creates a new resource each at unique locations.

But this use of Location in 201 is a lot more apparent when looking at
the use of POST for creating resources. But PUT isn't really that
different.

Regards
Henrik

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 4 Feb 2008 18:40:52 -0800

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.

On 31/01/2008, at 7:14 AM, Yves Lafon wrote:

>
> On Thu, 31 Jan 2008, Julian Reschke wrote:
>
>>> Should we keep this "multiple locations for one resource" paradigm?
>>
>> First of all, I do not agree with the "single new resource"  
>> interpretation. As Brian observed, that would be a conflict with  
>> RFC5023.
>
> In that case, we need to amend the current text as I read it as  
> implying there is only one new resource.
> Also:
> <<<
>   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].
>>>>
> Should be:
> <<<
>   If one single resource is created, a 201 response MAY contain...
>>>>
>
> -- 
> Baroula que barouleras, au tiéu toujou t'entourneras.
>
>        ~~Yves
>
>

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

---

From: Julian Reschke <[email-masked]>
Date: Tue, 05 Feb 2008 12:13:59 +0100

Yves Lafon wrote:
> 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.

So what kind of side effect would be updating a hit counter GIF? Or 
updating a list of "top referrers"?

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

Disagree. Why would you send a Location header for a successful 
(initial) PUT to a URI? Remember:

"The Location response-header field is used to redirect the recipient to 
a location other than the Request-URI for completion of the request or 
identification of a new resource." -- 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.14.30>

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

It should never differ, and only depend on the Request-URI + those 
request headers that select the variant.

> ...

BR, Julian

---

From: Henrik Nordström <[email-masked]>
Date: Tue, 05 Feb 2008 14:20:01 +0100

tor 2008-01-31 klockan 09:55 +1100 skrev Mark Nottingham:

> I find this just plain weird. On POST responses, it implies that you  
> can negotiate for response headers on another resource and get them  
> tunnelled back in the current response. If there's a Vary header  
> present, does it apply to that resource too? If not, how do you know  
> what the requested variant really was?

Content-Location, except that you can not blindly trust it due to
security implications... and we have already agreed that URIs indicated
by Content-Location SHOULD NOT be subject to server driven content
negotiation. Layering content negotiation ontop of those quickly leads
to recursive madness.

> On PUT responses, it's a little more sane, but the language forces the  
> requested variant to be the same as that just created; i.e., if  
> there's a chance of conneg, the Accept-* headers have to be set in  
> lockstep with what you're PUTting. So, you'd better not set Accept- 
> Encoding: gzip unless the request entity is also content-coded with  
> gzip, and AFAIK many implementations will have problems here, because  
> these mechanisms tend to be taken out of developers' hands.

It's the same in both as both may create a resource at a location
different than the requested URI. Even more obviously so in case of POST
than PUT as the request-URI of a POST is a data processing agent.. but
the principle on what is the actual created resource location is about
the same for both..

Regards
Henrik

---

From: Henrik Nordström <[email-masked]>
Date: Tue, 05 Feb 2008 14:33:54 +0100

tis 2008-02-05 klockan 07:33 -0500 skrev Yves Lafon:

> > It should never differ, and only depend on the Request-URI + those request 
> > headers that select the variant.
> 
> But in this case it may apply to another URI than request URI...

In both cases (200 Content-Location + ETag / 201 Location + ETag) & it
does, and both are subject to the same security implications that it's
not always safe to assume the response is authorative for the indicated
resource.

The two is really just two facets of the same concept of indicating that
the action was taken/resulter in a resorce at a different location than
the request-URI, with the main difference being the meaning of the
response entity.

The RFC wording is more strict on this wrt the use of Content-Location
than Location because associating the wrong response entity (+ ETag)
with a resource is a lot more dangerous than associating just a wrong
ETag..

Regards
Henrik

---

From: Yves Lafon <[email-masked]>
Date: Tue, 5 Feb 2008 05:54:39 -0500 (EST)

On Tue, 5 Feb 2008, Stefan Eissing wrote:

>
> Am 05.02.2008 um 03:40 schrieb Mark Nottingham:
>> 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???)

> - a ETag header on the response indicates the current value of the entity tag 
> for this requested variant (request uri or 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

         ~~Yves

---

From: Julian Reschke <[email-masked]>
Date: Tue, 05 Feb 2008 15:28:28 +0100

> directory automatically assigning a name to the created resource.

That would be contrary to how PUT is defined (I agree it would be useful 
- [1], but you can't do that with PUT).

BR, Julian

[1] <http://greenbytes.de/tech/webdav/draft-reschke-http-addmember-00.html>

---

From: Yves Lafon <[email-masked]>
Date: Tue, 5 Feb 2008 07:33:04 -0500 (EST)

On Tue, 5 Feb 2008, Julian Reschke wrote:

> So what kind of side effect would be updating a hit counter GIF? Or updating 
> a list of "top referrers"?

If the resource triggers the modification, then GET is misused, if it's a 
server configuration (filter, automatic log analysis), then the resource 
is not responsible for those side effects.

>> As the URIs should be in the entity of the response, the logic of !Location 
>> => request URI is wrong.
>
> Disagree. Why would you send a Location header for a successful (initial) PUT 
> to a URI? Remember:
>
> "The Location response-header field is used to redirect the recipient to a 
> location other than the Request-URI for completion of the request or 

I know about the definition of Location, but here we are not redirecting, 
just indicating the URI of the main newly created resource, and it can be 
done by only exposing it in the response entity (there is no MUST there).

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

         ~~Yves

---

From: Julian Reschke <[email-masked]>
Date: Tue, 05 Feb 2008 13:52:12 +0100

Yves Lafon wrote:
> If the resource triggers the modification, then GET is misused, if it's 
> a server configuration (filter, automatic log analysis), then the 
> resource is not responsible for those side effects.

That seems at best fuzzy to me. The distinction you mentioned seems to 
be an implementation detail, so not really relevant...

>> "The Location response-header field is used to redirect the recipient 
>> to a location other than the Request-URI for completion of the request 
>> or identification of a new resource." -- 
> I know about the definition of Location, but here we are not 
> redirecting, just indicating the URI of the main newly created resource, 
> and it can be done by only exposing it in the response entity (there is 
> no MUST there).

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

It should apply to the Request-URI.

BR, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 5 Feb 2008 07:11:32 -0800

> negotiation. Layering content negotiation ontop of those quickly leads

That implies that the response is a representation of the "other"  
resource, which is often not desirable.

---

From: Stefan Eissing <[email-masked]>
Date: Tue, 5 Feb 2008 10:19:35 +0100

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

So,

- 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???)
- a ETag header on the response indicates the current value of the  
entity tag for this requested variant (request uri or location)

//Stefan

--
<green/>bytes GmbH, Hafenweg 16, D-48155 Münster, Germany
Amtsgericht Münster: HRB5782

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 12 Feb 2008 22:25:25 -0800

I've only seen a few responses to one aspect of this, so I'll restate  
as a set of proposals.

On 30/01/2008, at 2:55 PM, Mark Nottingham wrote:

> Roy, when you said you'd be happy to replace it with  
> 'representation' do you mean
> 1) s/variant/representation/
> or
> 2) s/requested variant/representation/
> ?
>
> I think you mean #1, just want to make sure.
>
> My 0.02;
>
> It strikes me that if this term survives, or mutates into a new one,  
> the definition should be tied directly to the concepts of selecting  
> headers and the Vary header's payload. Tying it to conneg isn't good  
> enough -- there are multiple types of conneg. If we buy that, the  
> concept becomes more obviously tied to GET, and the issue of request  
> bodies / other methods falls away. I also think that we should limit  
> the use of such a term to places where we're talking about a  
> response (see below).

PROPOSAL: Remove 'requested variant' from terminology and define  
'selected representation' as (roughly): "The representation that would  
be returned by the server if the request method were GET, taking into  
consideration selecting headers, as specified by the Vary header's  
payload."

> (BTW, I note with interest that 14.44 doesn't classify Vary as a  
> particular type of header, as all (AFAICT) other headers are.)

This should be a new issue; I'll add one.

> WRT a name -- how about 'selected representation'? This emphasises  
> that it's the origin server doing the selection, not the client.
>
> I also think (again, personally) that this general problem area  
> would greatly benefit by having a crisper definition of and  
> terminology around the status of POST, PUT, DELETE and other non-GET  
> responses WRT whether they carry a representation or not.

PROPOSAL: Define the response to PUT, POST, DELETE, and OPTIONS to  
carry a "status message," not a representation, UNLESS a Content- 
Location is present OR (in the case of POST) there is explicit  
freshness information. As such, ETags, etc. do not apply to them.

(This is a straw-man that I expect this to be controversial; just  
trying to get things going...)

> I've pasted below all instances of 'variant' from 2616 outside of  
> the term's definition, with some (again, personal) comments. I'm  
> starting to suspect we have a number of inter-related issues here...
>
>
> 10.2.2 (201 Created):
>> created, see section 14.19.
> On PUT responses, it's a little more sane, but the language forces  
> the requested variant to be the same as that just created; i.e., if  
> gzip, and AFAIK many implementations will have problems here,  
> because these mechanisms tend to be taken out of developers' hands.

PROPOSAL:
A 201 response MAY contain an ETag response header field indicating  
the current value of the newly created resource's selected  
representation ETag (i.e., the ETag that would be returned if the same  
selecting headers had been sent in a GET request to it).

> 10.2.5 (204 No Content):
>> The server has fulfilled the request but does not need to return an  
>> entity-body, and might want to return updated metainformation. The  
>> response MAY include new or updated metainformation in the form of  
>> entity-headers, which if present SHOULD be associated with the  
>> requested variant.
>
> This makes internal sense; see comments about adjusting the  
> definition above.

PROPOSAL: s/requested variant/selected representation/

> 10.2.7 (206 Partial Content) and 10.3.5 (304 Not Modified):
>> The response MUST include the following header fields:
> [...]
>> - Expires, Cache-Control, and/or Vary, if the field-value might  
>> differ from that sent in any previous response for the same variant
>
> Here's where IMO a distinct term does add some value; if we said  
> 'representation', it would be tied to a particular entity, which  
> doesn't make much sense. OTOH 'variant' doesn't clarify things  
> greatly, as it's currently defined. "...any previous instance of the  
> selected representation'?

PROPOSAL: s/response for the same variant/instance of the selected  
representation/

> 14.14 (Content-Location)
>> The Content-Location entity-header field MAY be used to supply the  
>> resource location for the entity enclosed in the message when that  
>> entity is accessible from a location separate from the requested  
>> resource's URI. A server SHOULD provide a Content-Location for the  
>> variant corresponding to the response entity; especially in the  
>> case where a resource has multiple entities associated with it, and  
>> those entities actually have separate locations by which they might  
>> be individually accessed, the server SHOULD provide a Content- 
>> Location for the particular variant which is returned.
>
> This is where things get fairly muddy. Variant is currently defined  
> as a kind of representation, but here all of the sudden it's treated  
> as a resource and given a URI. The first instance could probably be  
> replaced by just 'resource', or just drop 'for the variant'  
> entirely; in the second, 'representation' would probably suffice.

PROPOSAL: s/for the variant//; s/the particular variant/the particular  
representation/

> 14.19 (ETag)
>> The ETag response-header field provides the current value of the  
>> entity tag for the requested variant.
>
> Makes sense here, but 'requested/selected representation' would do  
> just fine.

PROPOSAL: s/requested variant/selected representation/

> 14.25 (If-Modified-Since)
>> The If-Modified-Since request-header field is used with a method to  
>> make it conditional: if the requested variant has not been modified  
>> since the time specified in this field, an entity will not be  
>> returned from the server [...]
>> A GET method with an If-Modified-Since header and no Range header  
>> requests that the identified entity be transferred only if it has  
>> been modified since the date given by the If-Modified-Since header.  
>> The algorithm for determining this includes the following cases: a)  
>> If the request would normally result in anything other than a 200  
>> (OK) status, or if the passed If-Modified-Since date is invalid,  
>> the response is exactly the same as for a normal GET. A date which  
>> is later than the server's current time is invalid. b) If the  
>> variant has been modified since the If-Modified-Since date, the  
>> response is exactly the same as for a normal GET. c) If the variant  
>> has not been modified since a valid If- Modified-Since date, the  
>> server SHOULD return a 304 (Not Modified) response.
>
> 14.28 (If-Unmodified-Since)
>> If the requested variant has been modified since the specified  
>> time, the server MUST NOT perform the requested operation, and MUST  
>> return a 412 (Precondition Failed).
>
> 14.29 (Last-Modified)
>> The Last-Modified entity-header field indicates the date and time  
>> at which the origin server believes the variant was last modified.
> Interestingly, Last-Modified validation is defined in terms of  
> 'requested variant', whereas ETag validation (If-Match, If-None- 
> Match) seem to go out of their way to say that *any* entity that  
> meets the conditional can be returned, and never mind the selecting  
> headers. I'd be interested in hearing if any implementations  
> actually do that, and unless some are found, I'd suggest we need to  
> tighten up how ETag validation is defined..

PROPOSAL: s/requested variant/selected representation/g; s/variant/ 
selected representation/g

And, add an issue about the implied divergence in the ETag and LM  
validation models.

>
>
>
>
> On 10/01/2008, at 2:51 PM, Roy T. Fielding wrote:
>
>> On Jan 8, 2008, at 10:39 PM, Mark Nottingham wrote:
>>> Henrik mentioned a counterproposal in passing:
>>>
>>>> The "requested variant" is pretty clear. The variant returned had  
>>>> the
>>>> request been a GET request, or in case of the ETag returned by  
>>>> PUT a GET
>>>> request immediately after completion of the PUT.
>>>
>>> I've seen at least one other person agree (assumedly after  
>>> appropriate wordsmithing). Roy, thoughts?
>>
>> Variants are not returned.  I am happy to replace variant with the
>> right terminology (representation) if the WG doesn't mind.  That is
>> part of what I was talking about earlier when I said that 2616
>> often defines things in terms of server implementation when it
>> really should restrict itself to the visible interface.
>>
>> ....Roy
>>
>
>
> --

---

From: Julian Reschke <[email-masked]>
Date: Wed, 13 Feb 2008 14:35:03 +0100

Mark Nottingham wrote:
> 
> I've only seen a few responses to one aspect of this, so I'll restate as 
> a set of proposals.
> 
> ...
> 

+1

> PROPOSAL:
> A 201 response MAY contain an ETag response header field indicating the 
> current value of the newly created resource's selected representation 
> ETag (i.e., the ETag that would be returned if the same selecting 
> headers had been sent in a GET request to it).

+1

>> This makes internal sense; see comments about adjusting the definition 
>> above.
> 

+1

> PROPOSAL: s/response for the same variant/instance of the selected 

+1

>>> variant corresponding to the response entity; especially in the case 
>>> where a resource has multiple entities associated with it, and those 
>>> entities actually have separate locations by which they might be 
>>> individually accessed, the server SHOULD provide a Content-Location 
>>> for the particular variant which is returned.
>>
>> This is where things get fairly muddy. Variant is currently defined as 
>> a kind of representation, but here all of the sudden it's treated as a 
>> resource and given a URI. The first instance could probably be 
>> replaced by just 'resource', or just drop 'for the variant' entirely; 
>> in the second, 'representation' would probably suffice.
> 

The original text already is kind of confusing to me. First it makes a 
SHOULD level requirement; then it talks about a special case and points 
out what seems to be the same SHOULD level requirement. Maybe we need to 
rewrite the whole paragraph?

> PROPOSAL: s/requested variant/selected representation/

+1

>>> (OK) status, or if the passed If-Modified-Since date is invalid, the 
>>> response is exactly the same as for a normal GET. A date which is 
>>> later than the server's current time is invalid. b) If the variant 
>>> has been modified since the If-Modified-Since date, the response is 
>>> exactly the same as for a normal GET. c) If the variant has not been 
>>> modified since a valid If- Modified-Since date, the server SHOULD 
>>> return a 304 (Not Modified) response.
>>
>>> If the requested variant has been modified since the specified time, 
>>> the server MUST NOT perform the requested operation, and MUST return 
>>> a 412 (Precondition Failed).
>>
>> 14.29 (Last-Modified)
>>> The Last-Modified entity-header field indicates the date and time at 
>>> which the origin server believes the variant was last modified.
>> 'requested variant', whereas ETag validation (If-Match, If-None-Match) 
>> seem to go out of their way to say that *any* entity that meets the 
>> conditional can be returned, and never mind the selecting headers. I'd 
>> be interested in hearing if any implementations actually do that, and 
>> unless some are found, I'd suggest we need to tighten up how ETag 
>> validation is defined..

Sounds right to me.

> PROPOSAL: s/requested variant/selected representation/g; 
> s/variant/selected representation/g

+1

> And, add an issue about the implied divergence in the ETag and LM 

+1

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Wed, 13 Feb 2008 06:19:40 -0800

Mark Nottingham wrote:
> PROPOSAL: Define the response to PUT, POST, DELETE, and 
> OPTIONS to carry a "status message," not a representation, 
> UNLESS a Content- Location is present OR (in the case of 
> POST) there is explicit freshness information. As such, 
> ETags, etc. do not apply to them.

If there is a Content-Location, then that means that a representation of
the response body may be retrieved at the location given in it. That is,
the status message is stored on the server along with whatever resource
was being manipulated. If Content-Location = Location (for 201), then
resource being manipulated is the same as the status message (the
resource describes its own status). For some methods (e.g. PUT),
Location is implicitly the Request-URI. If Content-Location <> Location,
then the status message is a seperate resource from what was created,
and a representation of that status message is available at
<Content-Location>. You cannot make "status message" and
"representation" mutually exclusive. Status messages can also have
multiple representations if there is a Content-Location header (using
normal content negotiation at the Content-Location URI). And, a server
cannot return a representation of the manipulated resource *instead* of
a status message; if it returns a representation of the manipulated
resource, that representation *is* the status message.

> PROPOSAL: Remove 'requested variant' from terminology and 
> define 'selected representation' as (roughly): "The 
> representation that would be returned by the server if the 
> request method were GET, taking into consideration selecting 
> headers, as specified by the Vary header's payload."

If there are Accept-* headers, then those headers apply to the response
body (status message), not to the POSTed/PUT/DELETed resource. For
example, "Accept-Encoding: deflate" on a POST means that the server can
return a compressed status message.

This proposal seems to be saying that those headers are used to select
two representations of two different things at once: a representation of
the status message, and a representation of the resource(s) that are
being manipulated. The assumption is that the client will always send
the same Accept-* headers for the hypothetical GET that it sent during
its actual POST/PUT/DELETE. I don't think that assumption is valid.

> selecting headers had been sent in a GET request to it).

The above implies that only one resource was created. "the newly created
resource" should become a reference to the resource pointed to by the
Location header. Also, the hypothetical GET would have to happen on the
Location URI, not the Request URI, right?

> selected representation/g

When I POST with an If-Unmodified-Since or If-Match to an AtomPub
collection, doesn't that mean "Process this new entry only if the
collection hasn't been modified"? In other words, If-* headers must
refer to the resource that is available via a GET at the Request-URI--in
the case of AtomPub, the collection feed.

- Brian

---

From: Adrien de Croy <[email-masked]>
Date: Thu, 14 Feb 2008 03:35:21 +1300

Julian Reschke wrote:
>> 'selected representation' as (roughly): "The representation that 
>> would be returned by the server if the request method were GET, 
>> taking into consideration selecting headers, as specified by the Vary 
>> header's payload."
>
> +1
>

Quick question (hopefully) - what's the difference between 
"representation" in this case and "entity"?  I feel I'm missing something.

I like the reinforcement that it's the provider (server) that chooses 
what to provide.

Thanks

Adrien

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 14:21:48 +0100

> was being manipulated. If Content-Location = Location (for 201), then

...not necessarily stored, but made available.

> resource describes its own status). For some methods (e.g. PUT),

The representation sent back (not the resource) is the same as the 
status message.

> resource, that representation *is* the status message.

Yes. Does this really conflict with Mark's proposal though?

> return a compressed status message.

Well, it applies to the response, be it a representation or a status 
message.

> its actual POST/PUT/DELETE. I don't think that assumption is valid.

I think it is in practice.

If content negotiation occurs, it's the server's responsibility to make 
sure that PUT and DELETE behave in a sane way. That can be done by 
disallowing them (just supporting them on more specific URIs), or by 
doing the "right" thing (DELETE without Accept-Encoding also removes a - 
for instance - gziped variant).

> Location header. Also, the hypothetical GET would have to happen on the

Yes (with the special case for PUT).

> Location URI, not the Request URI, right?

That's tricky. I'd prefer this to only be based on Request-URI and 
request headers.

> the case of AtomPub, the collection feed.

I think this is what the proposal says.

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 14:25:29 +0100

> "representation" in this case and "entity"?  I feel I'm missing something.

OK, let's try.

A representation:

"An entity included with a response that is subject to content 
negotiation, as described in Section 12. There may exist multiple 
representations associated with a particular response status." -- 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.1.3>

An entity:

"The information transferred as the payload of a request or response. An 
entity consists of metainformation in the form of entity-header fields 
and content in the form of an entity-body, as described in Section 7."

So an entity can be a representation of a resource (such as for a 
successful GET), but doesn't need to be.

Maybe it would make sense to enumerate all cases where this is the case?

Such as:

- GET -> 200
- PUT -> 201 where Content-Location == Request-URI
- POST -> 201 where Content-Location == Location
- ...

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 06:30:22 -0800

Julian Reschke wrote:
> Brian Smith wrote:
> > If Content-Location = Location (for 201), then resource being 
> > manipulated is the same as the status message (the resource 
> > describes its own status). For some methods (e.g. PUT),
> 

To be clear, "representation" always implies "representation of the
resource," right?

> > Location is implicitly the Request-URI. If Content-Location <> 
> > Location, then the status message is a seperate resource from what 
> > was created, and a representation of that status message is 
> > available at <Content-Location>. You cannot make "status message" 
> > and "representation" mutually exclusive. Status messages can also 
> > have multiple representations if there is a Content-Location header 
> > (using normal content negotiation at the Content-Location URI).
> > And, a server cannot return a representation of the manipulated 
> > resource *instead* of a status message; if it returns a 
> > representation of the manipulated resource, that representation *is*

> > the status message.

The proposal was that those methods "carry a 'status message,' not a
representation." That "not a representation" phrase implies that the
status message cannot be a representation of the resource.

> > If there are Accept-* headers, then those headers apply to the 
> > response body (status message), not to the POSTed/PUT/DELETed 
> > resource. For example, "Accept-Encoding: deflate" on a POST means 
> > that the server can return a compressed status message.
> 

The response must always be a status message. The response may also be a
representation of the resource. The response can never be a
representation of the resource without also being a status message.

> > This proposal seems to be saying that those headers are used to 
> > select two representations of two different things at once: a 
> > representation of the status message, and a representation of the 
> > resource(s) that are being manipulated. The assumption is that the 
> > client will always send the same Accept-* headers for the 
> > hypothetical GET that it sent during its actual POST/PUT/DELETE. I 
> > don't think that assumption is valid.
> 
> If content negotiation occurs, it's the server's responsibility to 
> make sure that PUT and DELETE behave in a sane way. That can be done 
> by disallowing them (just supporting them on more specific URIs), or 
> by doing the "right" thing (DELETE without Accept-Encoding also 
> removes a
> - for instance - gziped variant).

Accept-* refer always to the response entity, not to the selected
representation. (Rather, the Accept-* headers are relevant for selecting
a representation only when a representation is returned in the response
entity.) If I have a DELETE with an Accept-Encoding, that means that I
want the status message for the request to be encoded a certain way; it
doesn't mean that I want to delete the representation that has that
encoding. In order to delete a specific representation of a resource,
each representation needs to have its own Content-Location. That is why
having separate Content-Locations for variants is a SHOULD-level
requirement in HTTP.

As another example, let's say I POST an image to a photo book
application, where the photo book application returns the URL of the
photo in the Location header of a 201 response, and returns a hyperlink
to it in the response entity. In my POST, I have "Accept:
text/plain;q=0.9, text/html;q=1.0" to state I prefer the hyperlink
(status message) to be in HTML, or plain text as a fallback. However, my
"Accept" header for the image is not going to be the same; it would be
"Accept: image/jpg;q=1.0, image/png;q=0.9" if I POSTed a JPEG, and
"Accept: image/png;q=1.0, image/jpg;q=0.9" if I posted a PNG. (The
intent here is to always prefer to get back something as close to what I
posted as possible.)

As another example, I can POST a Japanese document, where the request
has a "Content-Language: jp". But, I prefer English language status
messages, so I have "Accept-Language: en". With this proposal, the
server should return the ETag for an English representation even though
I am explicitly manipulating a Japanese representation. That is
counter-intuitive. Again, I set up my client so that it always attempts
to set its "Accept-*" headers to match the "Content-*" headers of
whatever was posted, so that I am most likely to retrieve the same
representation that I posted.

It would somewhat make sense if the server did its negotiation based on
the Content-* headers, not Accept-* headers. But, you cannot put
Content-* headers in a Vary header; Content-* are all entity headers,
and Vary: can only list request headers. And, this proposal says that
the server needs to list all the headers it used to select a variant in
the Vary header.

It would be better to say that servers should not return an ETag in
response a response unless there is only one variant ("selectable
representation"?) for that resource, or unless
Content-Location=Location, which means the response entity is both the
status message and the selected representation. Otherwise, the client
needs to choose which ETag it is interested in by sending a subsequent
GET or HEAD request with headers that the server can use to select a
representation.

> > Also, the hypothetical GET would have to happen on the Location URI,

> > not the Request URI, right?
> 

If I POST an image to an AtomPub collection, the ETag in the "201
Created" response must the one for the entry just created (in the
Location: header), not the feed document at the Request-URI.

> > refer to the resource that is available via a GET at the 
> > Request-URI--in the case of AtomPub, the collection feed.
> 

My concern is that the "hypothetical GET" that is part of the proposal
needs to be done against the Location: URI, not the Request URI. In the
proposal, when doing this hypothetical GET, the server would have to
consider some of the request headers, but it should ignore the If-*
headers, right? You have to partition request headers into ones that are
available for consideration when selecting a representation, and which
ones should/must not be used when selecting a representation.

- Brian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 06:43:42 -0800

Julian Reschke
> Brian Smith wrote:
> >Mark Nottingham wrote:
> >> PROPOSAL:
> >> A 201 response MAY contain an ETag response header field 
> >> indicating the current value of the newly created
> >> resource's selected representation ETag (i.e., the ETag
> >> that would be returned if the same selecting headers had
> >> been sent in a GET request to it).
> > 
> > The above implies that only one resource was created. "the
> > newly created resource" should become a reference to the
> > resource pointed to by the Location header. 
> 

What do you mean? A PUT can result in multiple resources being created,
and a 201 response for a PUT should have a Location header. Actually,
section 10.2.2 of RFC 2616 doesn't say "should" but I think that is the
intent.

- Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 16:02:38 +0100

> To be clear, "representation" always implies "representation of the

Yes, it should.

> status message cannot be a representation of the resource.

"PROPOSAL: Define the response to PUT, POST, DELETE, and OPTIONS to 
carry a "status message," not a representation, UNLESS a 
Content-Location is present OR (in the case of POST) there is explicit 
freshness information."

So maybe it needs to be rephrased but it certainly does cover the case 
where the response is a representation of the resource.

> representation of the resource without also being a status message.

I have no problem with defining it this way.

> a representation only when a representation is returned in the response

Disagreed.

> encoding. In order to delete a specific representation of a resource,

It seems to me that questions like these are the ones we want to answer 
in the context of this issue.

Does it make a difference in practice? How do you distinguish between 
request headers that affect the selected representation, and those that 
only affect status messages?

> having separate Content-Locations for variants is a SHOULD-level

I don't think it is; all I can see is a "SHOULD send Content-Location 
when separate URI exists".

> intent here is to always prefer to get back something as close to what I

But the URI you POST to, and the photo URI are distinct; so I don't see 
why that's surprising.

> representation that I posted.

OK, so tying the ETag to Location for 201 would fix this. That may be 
the right thing to do, but I'd still like to leave the definition of 
"selected representation" as simple as possible.

> GET or HEAD request with headers that the server can use to select a

Nice in theory. In practice, many resources have at least two 
representations (the raw one, and with Content-Encoding: gzip).

> Location: header), not the feed document at the Request-URI.

Understood. So minimally in this case, the ETag is not for the selected 
representation.

> needs to be done against the Location: URI, not the Request URI. In the

Hm, why would it need to be done against anything except the 
Request-URI? Me confused :-)

> ones should/must not be used when selecting a representation.

Which one would not be used for the selection?

BR, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 16:07:12 +0100

> section 10.2.2 of RFC 2616 doesn't say "should" but I think that is the

In general, there's no point in sending a Location header for a 201 
response to PUT. If the resource was not created at the Request-URI, the 
request shouldn't have succeeded in the first place.

And, as far as I recall from debugging WebDAV traffic, many servers 
indeed do not include the header.

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 08:18:06 -0800

Julian Reschke wrote:
> Brian Smith wrote:
> > What do you mean? A PUT can result in multiple resources being 
> > created, and a 201 response for a PUT should have a 
> > Location header. 
> > Actually, section 10.2.2 of RFC 2616 doesn't say "should" 
> > but I think that is the intent.
> 
> In general, there's no point in sending a Location header for 
> a 201 response to PUT. If the resource was not created at the 
> Request-URI, the request shouldn't have succeeded in the first place.
> 
> And, as far as I recall from debugging WebDAV traffic, many 
> servers indeed do not include the header.

If the intent is that the header is to be optional, or optional only for
specific methods and required for others, then that should stated
explicitly using RFC 2119 language. The current wording, "the newly
created resource can be referenced by the URI(s) returned in the entity
of the response, with the most specific URI for the resource given by a
Location header field," implies that the client can assume the Location
header is always there, which is why I interpret it as being required.

- Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 17:40:02 +0100

> header is always there, which is why I interpret it as being required.

Good point.

In reality, many servers do not return it for PUT (as it would be 
redundant), so I think the spec needs to allow that.

(Mark, new issue?)

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 08:56:42 -0800

Julian Reschke wrote:
> > representation. (Rather, the Accept-* headers are relevant for 
> > selecting a representation only when a representation is 
> returned in 
> > the response
> 
> Disagreed.
>
> > entity.) If I have a DELETE with an Accept-Encoding,
> > that means that I want the status message for the request
> > to be encoded a certain way; it doesn't mean that I want
> > to delete the representation that has that encoding. In
> > order to delete a specific representation of a resource,
> 
> It seems to me that questions like these are the ones we want 
> to answer in the context of this issue.
> 
> Does it make a difference in practice? How do you distinguish 
> between request headers that affect the selected 
> representation, and those that only affect status messages?

I base my statement on "The Accept request-header field can be used to
specify certain media types which are acceptable for the response" and
many other similar statements in sections 14.1-5. Clearly, the intent is
that the Accept-* headers always specify the client's preferences
regarding the response entity. 

Is this set of proposals intended to define how to edit a specific
representation of a content-negotiated resource? I think it is pretty
clear how it works when each separately-editable representation has its
own URI (see below about Content-Location). Why isn't that good enough? 

Example: A resource http://example.org/foo has two representations: one
application/pdf, and one text/html. The client wishes to modify the PDF
representation. However, it cannot display PDF content in its error
dialog boxes, so it wants the status message to come back as text/html.
Under this proposal, the client would have to specify "Accept:
application/pdf" in order to edit the PDF representation. However, this
also indicates that it wants a PDF response entity, when really it
doesn't want that at all. If it has "Accept: text/html" then, under this
proposal, the server may interpret that as a request to edit only the
HTML representation. 

It is also confusing what "selected representation" means with POST. Is
the "selected representation" a representation of the resource at the
Request-URI, or is the "selected representation" a representation of the
resource that was created? It seems like you always intend for it to be
the former, but there are many applications that expect the Accept-*
headers to refer to the latter when Location=Content-Location.

Also, if I POST with "Accept: image/jpg;q=1.0, image/png;q=0.9" to an
AtomPub collection, should I expect the AtomPub collection to return a
"406 Not Acceptable" response, since the collection does not have a JPEG
or a PNG representation?

> > That is why having separate Content-Locations for variants
> > is a SHOULD-level requirement in HTTP.
> 
> I don't think it is; all I can see is a "SHOULD send 
> Content-Location when separate URI exists".

I stand corrected. In practice, however, this is basically a requirement
for resources with distinctly editable representations, because the only
defined content negotiation mechanism is for response entities, and the
client would not be able to determine ahead of time whether the server
supports this new proposed mechanism.

> > application, where the photo book application returns the 
> > URL of the photo in the Location header of a 201 response, and 
> > returns a hyperlink to it in the response entity. In my POST, I 
> > have "Accept: text/plain;q=0.9, text/html;q=1.0" to state I 
> > prefer the hyperlink (status message) to be in HTML, or plain 
> > text as a fallback. However,  my "Accept" header for the image
> > is not going to be the same; it would  be
> > "Accept: image/jpg;q=1.0, image/png;q=0.9" if I POSTed a JPEG, 
> > "Accept: image/png;q=1.0, image/jpg;q=0.9" if I posted a PNG.
> > (The intent here is to always prefer to get back something as 
> > close to what I posted as possible.)
> 
> But the URI you POST to, and the photo URI are distinct; so I 
> don't see why that's surprising.

I misunderstood what you intended "selected representation" to mean for
POST. In particular, I thought "selected representation" referred to the
representation whose ETag is returned in a "201 Created" response.

> > As another example, I can POST a Japanese document, where 
> > the request has a "Content-Language: jp". But, I prefer English 
> > language status messages, so I have "Accept-Language: en". With 
> > this proposal, the server should return the ETag for an English 
> > representation even though I am explicitly manipulating a 
> > Japanese representation. That is counter-intuitive. Again,
> > I set up my client so that it always attempts to set its 
> > "Accept-*" headers to match the "Content-*" headers of whatever 
> > was posted, so that I am most likely to retrieve the same 
> OK, so tying the ETag to Location for 201 would fix this. 
> That may be the right thing to do, but I'd still like to 
> leave the definition of "selected representation" as simple 
> as possible.

ETag and Location are already tied together: "A 201 response MAY contain
an ETag response header field indicating the current value of the entity
tag for the requested variant just created." But, if multiple variants
were created (e.g. compressed and uncompressed), then the client doesn't
know which variant the ETag refers to. That was why I thought that
"selected representation" meant something different for POST.

> > It would be better to say that servers should not return an
> > ETag in a response unless there is only one variant
> > ("selectable representation"?) for that resource, or unless 
> > Content-Location=Location, which means the response entity 
> > is both the status message and the selected representation.
> > Otherwise, the client needs to choose which ETag it is
> > interested in by sending a subsequent GET or HEAD request with 
> > headers that the server can use to select a representation.
> 

PROPOSAL: When Location=Content-Location, the ETag must be the one for
the representation returned as the response entity. Otherwise, the
server may return the ETag for any representation of the resource; the
client cannot determine which representation that ETag is for, and
should do a HEAD or GET to retrieve the ETag for the representation it
is interested in, if it needs a specific one.

> Understood. So minimally in this case, the ETag is not for 
> the selected representation.

> > My concern is that the "hypothetical GET" that is part of 
> > the proposal needs to be done against the Location: URI,
> > not the Request URI. 

> Request-URI? Me confused :-)

I was thinking "selected representation" referred to the representation
of the newly-created resource that had the ETag given in response. If
that is not what "selected representation" refers to, then maybe there
needs to be another new term coined.

> > headers, right? You have to partition request headers into 
> ones that 
> > are available for consideration when selecting a 
> representation, and 
> > which ones should/must not be used when selecting a representation.
> 

Again, this comes from my misunderstanding of what was meant by
"selected representation" for POST.

- Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 18:28:40 +0100

> regarding the response entity. 

Agreed. The question is whether they *also* select a representation, 
before the response entity is generated.

If we do not do that, we'll have to distinguish between headers 
selecting a representation, and those selecting the format of a status 
message. Which seems like a bad idea to me.

> own URI (see below about Content-Location). Why isn't that good enough? 

I think it is good enough, and we shouldn't try to do more.

> proposal, the server may interpret that as a request to edit only the

...which is why it's good to have separate URIs for the authorable variants.

> headers to refer to the latter when Location=Content-Location.

I'd prefer it to be the former for all methods, which doesn't rule out 
to *also* apply to the status message.

> "406 Not Acceptable" response, since the collection does not have a JPEG

That would be consistent with what I propose.

Why would you POST with that Accept header, btw?

> supports this new proposed mechanism.

No disagreement here.

> "selected representation" meant something different for POST.

OK.

> is interested in, if it needs a specific one.

Sounds ok.

> needs to be another new term coined.

Due to my WebDAV history, I frequently think about PUT, when people are 
creating things with POST. Obviously, with PUT things are more simple.

And yes, it seems that for POST->201 we need terms for two different things.

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 09:51:58 -0800

> > I base my statement on "The Accept request-header field can 
> > be used to specify certain media types which are acceptable
> > for the response" and many other similar statements in
> > sections 14.1-5. Clearly, the intent is that the
> > Accept-* headers always specify the client's preferences 
> Agreed. The question is whether they *also* select a 
> representation, before the response entity is generated.
> 
> If we do not do that, we'll have to distinguish between 
> headers selecting a representation, and those selecting the 
> format of a status message. Which seems like a bad idea to me.
> 
> > representation of a content-negotiated resource? I think it 
> > is pretty clear how it works when each separately-editable
> > representation has its own URI (see below about Content-Location).
> > Why isn't that good enough?
> 

If you don't want to define a new mechanism for editing specific
representations, then why do you need to "select a representation before
the response entity is generated"? 

> > Also, if I POST with "Accept: image/jpg;q=1.0, 
> > image/png;q=0.9" to an AtomPub collection, should I expect
> > the AtomPub collection to return a "406 Not Acceptable"
> > response, since the collection does not have a 
> > JPEG or a PNG representation?
> 

I messed the example up. If I POST with "Accept:
application/atom+xml;type=entry" then can the server respond with "406
Not Acceptable" since the collection (at the Request-URI) has type
application/atom+xml;type=feed? 

If I PUT to an image's location with "Accept: text/html", can the server
respond with "406 Not Acceptable" since it doesn't have an HTML
representation of the image? How could the client say it wanted status
messages in HTML while editing an image?

- Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 19:05:43 +0100

> the response entity is generated"? 

Because I'd like "selected representation" to be independent of request 
methods.

> application/atom+xml;type=feed? 

406 doesn't seem to allow that:

"The resource identified by the request is only capable of generating 
response entities which have content characteristics not acceptable 
according to the accept headers sent in the request." -- 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.10.4.7>

So the error condition applies to the process of generating the 
response, not selecting a representation.

> messages in HTML while editing an image?

See above.

Which doesn't mean I am happy with how things are -- but that's why we 
are having this discussion. (And we have it because the RFC2616 term 
"requested variant" doesn't work well with anything except HEAD/GET).

BR, Julian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Thu, 14 Feb 2008 10:49:53 -0800

> <http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.1.3>

Yikes, no thanks.

> An entity:
>
> "The information transferred as the payload of a request or  
> response. An entity consists of metainformation in the form of  
> entity-header fields and content in the form of an entity-body, as  
> described in Section 7."

That is a representation.  I was hoping to replace entity at some  
point for
that reason.  The payload is always a representation of *some*  
resource.  The
status code tells us which resource it is, and Content-Location tells  
us its
most specific URI.

Getting back to Mark's proposal regarding 'requested variant'... I think
that is headed in the right direction but will need some tweaks.

    PROPOSAL: Remove 'requested variant' from terminology and define
    'selected representation' as (roughly): "The representation that  
would be
    returned by the server if the request method were GET, taking into
    consideration selecting headers, as specified by the Vary  
header's payload."

I would say that it is: "The representation that would be returned by  
the
origin server if the request method were GET and the response status  
200."

Note that Vary is one of those fields that is overspecified in 2616.
Vary is supposed to be instructions to any downstream caches, not a
limitation on origin server implementation.  A server is fully within  
its
rights to vary its representations however it likes without telling
the downstream recipients -- it only needs to tell the client what it
requires of any downstream cache keys (i.e., the interface requirement).

    PROPOSAL: Define the response to PUT, POST, DELETE, and OPTIONS  
to carry
    a "status message," not a representation, UNLESS a Content- 
Location is
    present OR (in the case of POST) there is explicit freshness  
information.
    As such, ETags, etc. do not apply to them.

trying
    to get things going...)

Er, I don't think so.  It really isn't that hard to distinguish between
a representation of the requested resource and a representation included
as payload within a message, even when we take into consideration the
206 partial responses (a representation of a set of ranges of the  
selected
representation).  Note that "status messages" are also subject to
negotiation.

    PROPOSAL:
    A 201 response MAY contain an ETag response header field  
indicating the
    current value of the newly created resource's selected  
representation ETag
    (i.e., the ETag that would be returned if the same selecting  
headers had
    been sent in a GET request to it).

By "newly created resource" and "to it", I assume you mean the resource
identified by the Location header field for POST and by the requested  
URI
for PUT.  Better to just say that.

The other spots that requested variant is used are all within  
sections that
need a general rewrite.

....Roy

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 11:33:36 -0800

> representation ETag (i.e., the ETag that would be returned if 
> the same selecting headers had been sent in a GET request to it).

> > 10.2.5 (204 No Content):
> >> The server has fulfilled the request but does not need to 
> >> return an entity-body, and might want to return updated 
> >> metainformation. The response MAY include new or updated
> >> metainformation in the form of entity-headers, which if
> >> present SHOULD be associated with the requested variant.
> >

There are many servers deployed that do not implement this. In
particular, there are servers that will return an ETag for an
uncompressed variant of the newly-created resource in a "201 Created",
ignoring the Accept-Encoding header of the POST that created the
resource. But, if the same Accept-Encoding header is used in a GET to
the selected representation, a different ETag (the one for the
compressed variant) would have been returned. And, similar problems
arise with entity headers (in particular, Content-MD5, Content-Length).
Such servers are currently conforming with RFC 2616 but would become
nonconforming if the proposed changes were made.

The Vary header cannot be used here because the server might not have
varied its response to the POST/PUT/DELETE, but it may vary its response
to a GET on the newly created resource. Also, as was mentioned by other
people, the response often depends on the request body, but there is no
way to indicate that except with "Vary: *", which is useless for what is
intended here.

> > 14.14 (Content-Location)
> >> The Content-Location entity-header field MAY be used to 
> >> supply the resource location for the entity enclosed in the
> >> message when that entity is accessible from a location separate
> >> from the requested resource's URI. A server SHOULD provide
> >> a Content-Location for the variant corresponding to the
> >> response entity; especially in the case where a resource has
> >> multiple entities associated with it, and those entities
> >> actually have separate locations by which they might  

> PROPOSAL: s/for the variant//; s/the particular variant/the 
> particular representation/

I suggest keeping the first sentence, and dropping everything after.
Elsewhere in the specification, include the advice that resources with
multiple representations should make each representation available at a
distinct URI.

> >> The If-Modified-Since request-header field is used with a 
> >> method to make it conditional: if the requested variant has
> >> not been modified since the time specified in this field, an
> >> entity will not be returned from the server [...]

> >> time, the server MUST NOT perform the requested operation, 
> >> and MUST return a 412 (Precondition Failed).

> > meets the conditional can be returned, and never mind the 
> > selecting headers. I'd be interested in hearing if any
> > implementations actually do that, and unless some are found,
> > I'd suggest we need to tighten up how ETag validation is defined..

This implies that A PUT/POST/DELETE with an If-Modified-Since or
If-Unmodified-Since applies to a specific representation. But, there is
no way to select a specific representation for any method whose response
entity isn't a representation of the resource. I suggest "if the
requested variant" should be replaced by "if any representation". This
also makes it consistent with If-Match and If-None-Match.

- Brian

---

From: "Brian Smith" <[email-masked]>
Date: Thu, 14 Feb 2008 12:39:26 -0800

Julian Reschke wrote:
> > representations, then why do you need to "select a representation 
> > before the response entity is generated"?
> 
> Because I'd like "selected representation" to be independent 
> of request methods.

There is no such thing as a (client-)"selected representation" or a
(client-)"requested variant." There is only the "client-selected
resource" and the "server-selected variants." The client requests an
operation to be performed on a resource specified by the Request URI,
and the server selects one or more variants of that resource to operate
on. The server may or may not select variants based on the request
headers, and it may or may not use other criteria to select variants. It
does not need to indicate to the client which variants it selected. The
client cannot compel the server to select particular variants of a
resource to operate on.

If the client wants to operate on a particular representation of a
resource, then it should find a resource URI for that representation. A
client may discover this URI via the Content-Location header that the
server returned with that representation, or some other mechanism. If
so, then the client may attempt to operate on the representation as a
distinct resource by using that URI as the Request URI. Or, it might not
be able to find such a URI, in which case the client cannot operate on
the it distinctly from other representations of the same resource.

At least, the above is how HTTP currently works. And, that seems to be
how we want HTTP to move (everything that needs to be independently
addressable has its own URI). So, whatever special support PROPFIND
needs should be localized to the specification of PROPFIND. And, new
methods like PATCH need to be brought in line with the above model if
they aren't already. But, HTTP itself does not need to change, except to
clarify the above.

- Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 14 Feb 2008 21:50:13 +0100

> client cannot compel the server to select particular variants of a

Yes.

> the it distinctly from other representations of the same resource.

Yes.

> they aren't already. But, HTTP itself does not need to change, except to

I agree with all of this. And I don't think we're trying to change HTTP. 
I also don't think PROPFIND needs special support. As a matter of fact, 
I'd like PROPFIND to work the same way as any other method.

BR, Julian

---

From: Robert Siemer <[email-masked]>
Date: Fri, 15 Feb 2008 02:28:25 +0100

> origin server if the request method were GET and the response status  

That inter-method-dependency is unacceptable. You say that the server 
may even select a representation based on whatever it wants, but it 
can't make it method dependend?

A POST may perfectly select the representation of the response based on 
some Accept-* headers, but the server may not even return something 
similar on GET at all. (Not to speak of any new/unknown method.)

And a GET -> "410 Gone" with a long long explanation could have a 
selected representation (in the language of the clients choice 
explaining why something is gone) as well.

Accept-* request headers express the wishes of the client on how to 
answer that request. They should not be overloaded with request 
entity attributes out of two reasons:
-use Content-* for that
-it's name (hey, it is called "Accept")

Entity response headers apply to the response entity with the miserable 
exceptions being marked with Location: on 201 responses. That means the 
Location header is already overloaded.

So I would define the "selected representation" as: "The representation 
selected by the server based on request headers and/or other factors."

Roy, do you mean that all response entities are "representations"?

> requires of any downstream cache keys (i.e., the interface requirement).

Robert

---

From: "Roy T. Fielding" <[email-masked]>
Date: Thu, 14 Feb 2008 17:51:15 -0800

> can't make it method dependend?

No, that isn't what we are talking about.  We are trying to find a way
to describe just one of the set of values (representations) that are
current for a given resource and then use that name to indicate
other requirements having to do with etags, other methods, etc.

Personally, I would prefer to just rewrite the sections so that
they make sense without knowing anything about the implementation
behind the interface.  But that requires serious thought and a lot
less emails to read.

...
> selected by the server based on request headers and/or other factors."

Then you would be talking about the payload within the response, not
the (formally known as "requested variant") that is the topic of this
discussion.

> Roy, do you mean that all response entities are "representations"?

Yes.  See

<http://www.ics.uci.edu/~fielding/pubs/dissertation/ 
rest_arch_style.htm#sec_5_2_1_2>

....Roy

---

From: "Brian Smith" <[email-masked]>
Date: Fri, 15 Feb 2008 01:38:40 -0800

Roy T. Fielding wrote:
> Personally, I would prefer to just rewrite the sections so 
> that they make sense without knowing anything about the 
> implementation behind the interface.  But that requires 
> serious thought and a lot less emails to read.

This should be done before trying to resolve i69. Rewriting these
sections will reduce the number of ways that "requested variant" is
used. The remaining uses of the term can then be analyzed to come up
with a definition of "selected representation" (or whatever) that works.
I believe that such a term will only be needed to describe GET, HEAD,
and 303 Not Modified. In other words, "requested variant" or "selected
representation" or whatever is truly a concept specific to GET and HEAD.

> > So I would define the "selected representation" as: "The 
> > representation selected by the server based on request 
> headers and/or 
> > other factors."
> 
> Then you would be talking about the payload within the 
> response, not the (formally known as "requested variant") 
> that is the topic of this discussion.

That is the only use of "requested variant" that makes any sense at all
when replaced by "(server-)selected representation."

"Requested variant" doesn't make any sense for the description of "201
Created" and "204 No content" because the client does not have any way
of requesting a particular variant to use for the ETag (201) or the
entity headers (204). The only option that works is to let the server
return the ETag/entity headers for *any* representation of that
resource.

"Requested variant" is nonsensical when describing
If-Modified-Since/If-Unmodified-Since for any method except GET and
HEAD. The server may reject the request with a 412 if any variant fails
to meet the preconditions, or it may process the request if any of the
variants do meet the preconditions; there are currently many servers
deployed that work each way. But, the client doesn't have any way of
telling the server that only one particular variant should be checked
against the preconditions. There is a special case for GET and HEAD, in
that a 304 Not Modified may be returned instead of whatever
representation the server would have returned in a 200 OK response, if
that representation meets the preconditions.

Content-Location does not refer to a particular variant. Instead, it
refers to a set of variants; that is, the Content-Location refers to a
resource, not a variant/representation. Otherwise, the server would not
be able to use content negotiation for any URL that is used in a
Content-Location header. Many servers DO content-negotiation at the
Content-Location URL; a lot of AtomPub implementations do, for example.

- Brian

---

From: Subbu Allamaraju <[email-masked]>
Date: Mon, 25 Feb 2008 12:59:22 -0800

If creating multiple resources via POST is indeed a valid  
interpretation of 2616, could this be clarified in the 2616bis?

Thanks
Subbu

On Feb 4, 2008, at 6:40 PM, Mark Nottingham wrote:

>> Baroula que barouleras, au

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 27 Feb 2008 10:22:30 +1100

I'd be OK with adding a non-normative example, at the most; adding  
normative language for this would imply that we're defining a sever- 
side model for how HTTP should be implemented, which (as Roy has  
pointed out several times), isn't a good idea.

Cheers,

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Feb 2008 12:55:07 +1100

Now <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/106>

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Feb 2008 12:56:58 +1100

Issue referenced at the bottom is <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/107 
 >.

On 13/02/2008, at 5:25 PM, Mark Nottingham wrote:

>>> The If-Modified-Since request-header field is used with a method  
>>> to make it conditional: if the requested variant has not been  
>>> modified since the time specified in this field, an entity will  
>>> not be returned from the server [...]
>>> been modified since the date given by the If-Modified-Since  
>>> header. The algorithm for determining this includes the following  
>>> cases: a) If the request would normally result in anything other  
>>> than a 200 (OK) status, or if the passed If-Modified-Since date is  
>>> invalid, the response is exactly the same as for a normal GET. A  
>>> date which is later than the server's current time is invalid. b)  
>>> If the variant has been modified since the If-Modified-Since date,  
>>> the response is exactly the same as for a normal GET. c) If the  
>>> variant has not been modified since a valid If- Modified-Since  
>>> date, the server SHOULD return a 304 (Not Modified) response.
>>
>>> time, the server MUST NOT perform the requested operation, and  
>>> MUST return a 412 (Precondition Failed).
>>
>> 14.29 (Last-Modified)

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 28 Feb 2008 16:00:13 +1100

As I said in a separate e-mail just now, I think the definition of  
entity and representation deserves to be a new issue.

Roy - my personal feedback here is that while there's internal logic  
to what you say, it conflicts pretty deeply with the terminology  
already in 2616, which is what most people (including myself) base  
their understanding upon. As such, I wonder if the least surprising /  
disruptive thing to do would be to adapt the concepts and terminology,  
rather than swap them out.

I understand that in theory, everything can have a URI (i.e., has the  
potential for being associated with a resource), but the current split  
of terminology seems to nicely acknowledge the fact that the common  
case is to talk about the representation of the explicitly identified  
resource (i.e., the one in either the request-URI or the Content- 
Location header, as appropriate).

To put it another way -- if a representation doesn't have a URI, is it  
still useful to call it a representation?

Beyond that, I wonder at the choice of terms here:
> representation An entity included with a response that is subject to  
> content negotiation, as described in section 12. There may exist  
> multiple representations associated with a particular response status.

I'd understand this if the last sentence ended with "particular  
resource" but "particular response status" seems like an odd thing to  
say so generically. Anybody want to shed light on why this is as it is?

On 15/02/2008, at 5:49 AM, Roy T. Fielding wrote:

> status code tells us which resource it is, and Content-Location  
> tells us its
> most specific URI.

---

From: Subbu Allamaraju <[email-masked]>
Date: Thu, 28 Feb 2008 08:25:09 -0800

That should be good enough.

Thanks Mark.

Subbu