Subject: draft-whitehead-http-etag, Content-Location and 200 OK

From: Mark Nottingham <[email-masked]>
Date: Mon, 3 Apr 2006 15:11:41 -0700

draft-whitehead-http-etag-00 section 4.1 points out problems with the  
semantics of ETags in responses; specifically, saying that while  
their semantics is covered in 201 responses (depending on how you  
interpret "requested variant"), the specifications of 200 and 204 are  
silent about this.

I don't think that's quite the case for 204, which says;
> 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.
Although it's a SHOULD-level requirement, arguably this is enough.

I think the real problem is that 200 is under-specified (or over- 
loaded); while it works well with GET responses, several methods  
(POST, PUT, DELETE) use 200 responses to transfer a successful status  
entity, separate from the entity that would have been returned upon a  
successful GET (what some might call an "instance" or  
"representation; *ducks*).

Because of this, there's a potential conflict between the entity  
headers for the actual response message, vs. those that would be  
returned upon a GET. This isn't the case with 201 and 204, which can  
only convey a status message or nothing, respectively.

I don't think this problem is limited to ETags; e.g., I have users  
who want to return a Content-Location on the response to a PUT,  
because the GET would return a C-L, but they can't because of this.

In a strict reading, C-L applies to the entity it appears within,  
although there are inconsistencies; e.g., in 14.14,
> 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.
vs. 14.30,

> Note: The Content-Location header field (section 14.14) differ from  
> Location in that the Content-Location identifies the original  
> location of the entity enclosed in the request. It is therefore  
> possible for a response to contain header fields for both Location  
> and Content-Location. Also see section 13.10 for cache requirements  
> of some methods.

Am I making sense?

Until this is cleared up, I think I'm going to tell people to use 204  
No Content when they want to update a resource's metadata on a PUT  
response.

--
Mark Nottingham
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 04 Apr 2006 20:47:32 +0200

Mark Nottingham wrote:
> semantics of ETags in responses; specifically, saying that while their 
> semantics is covered in 201 responses (depending on how you interpret 
> "requested variant"), the specifications of 200 and 204 are silent about 
> this.
> 

That would be correct, but "ETag" isn't an entity-header 
(<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.7.1>) but a 
Response Header 
(<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.6.2>).

Which of course leads to the question: what's the difference??? Looking 
at 6.2...:

"The response-header fields allow the server to pass additional 
information about the response which cannot be placed in the 
Status-Line. These header fields give information about the server and 
about further access to the resource identified by the Request-URI."

...seems to be relevant here as it really seems to support the 
"the-etag-is-for-the-entity-you'd-get-on-a-subsequent-GET" world view.

So unless I misread that part, RFC2616 indeed seems to say what ETags in 
PUT responses mean. Which is good. Because we then just need to clarify; 
and can also think about extensions such as in 
<http://greenbytes.de/tech/webdav/draft-whitehead-http-etag-00.html#rfc.section.5>.

> I think the real problem is that 200 is under-specified (or 
> over-loaded); while it works well with GET responses, several methods 
> successful GET (what some might call an "instance" or "representation; 
> *ducks*).

Agreed (including the very last part :-).

> Because of this, there's a potential conflict between the entity headers 
> for the actual response message, vs. those that would be returned upon a 
> GET. This isn't the case with 201 and 204, which can only convey a 
> status message or nothing, respectively.
> 
> I don't think this problem is limited to ETags; e.g., I have users who 
> want to return a Content-Location on the response to a PUT, because the 
> GET would return a C-L, but they can't because of this.
> 
>> Location in that the Content-Location identifies the original location 
>> of the entity enclosed in the request. It is therefore possible for a 
>> response to contain header fields for both Location and 
>> Content-Location. Also see section 13.10 for cache requirements of 
>> some methods.
> 
> Am I making sense?

I'm with you that there seems to be a problem. Do you have a suggestion 
how to fix it?

> Until this is cleared up, I think I'm going to tell people to use 204 No 
> Content when they want to update a resource's metadata on a PUT response.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 4 Apr 2006 12:08:46 -0700

On 2006/04/04, at 11:47 AM, Julian Reschke wrote:
>
> That would be correct, but "ETag" isn't an entity-header (<http:// 
> greenbytes.de/tech/webdav/rfc2616.html#rfc.section.7.1>) but a  
> Response Header (<http://greenbytes.de/tech/webdav/ 
> rfc2616.html#rfc.section.6.2>).

Ah, my bad. Thought I'd checked that.

> Which of course leads to the question: what's the difference???  
> Looking at 6.2...:
>
> information about the response which cannot be placed in the Status- 
> Line. These header fields give information about the server and  
> ...seems to be relevant here as it really seems to support the "the- 
> etag-is-for-the-entity-you'd-get-on-a-subsequent-GET" world view.

OK. If we were *really* picking apart 2616, I'd think a re-org of the  
header classifications would be in order; Jeff M took a stab at this  
in "Clarifications of the Fundamentals of HTTP."

> I'm with you that there seems to be a problem. Do you have a  
> suggestion how to fix it?

Not sure yet, but I was thinking about a new 2xx status code to be  
explicitly used as a successful non-GET/POST response (both GET and  
POST responses can be cacheable). Problem is, 200 is hard-wired as  
the code to use in a number of places (e.g., the definition of PUT).

OTOH, 204 may be good enough for most cases; is it that often that  
it's necessary to return an entity body with the PUT response? If the  
scope of metainformation updates in the definition of 204, or the  
definition of entity-headers, can be adjusted just a bit, it should  
be adequate, I think. After all, what other possible meaning could an  
ETag have in a 204 response?

--
Mark Nottingham
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 04 Apr 2006 21:25:42 +0200

Mark Nottingham wrote:
> ...
> header classifications would be in order; Jeff M took a stab at this in 
> "Clarifications of the Fundamentals of HTTP."

The problem is that the group of people interested in this topic (= the 
readers of this mailing list) do not seem to agree upon whether the spec 
needs to be clarified, and if it needs to, how to proceed. Every few 
months we're exchanging a few mails about this topic, but in the end the 
discussion dies away.

Right now, do we have just have an editorial problem, getting the 
changes that Jim Gettys made in <draft-gettys-http-v11-spec-rev-00> into 
the XML version of RFC2616, thereby getting (hopefully) easy-to-review 
diffs? In that case, I'm volunteering to integrate them.

> explicitly used as a successful non-GET/POST response (both GET and POST 
> responses can be cacheable). Problem is, 200 is hard-wired as the code 
> to use in a number of places (e.g., the definition of PUT).
> 
> OTOH, 204 may be good enough for most cases; is it that often that it's 
> necessary to return an entity body with the PUT response? If the scope 
> of metainformation updates in the definition of 204, or the definition 
> of entity-headers, can be adjusted just a bit, it should be adequate, I 
> think. After all, what other possible meaning could an ETag have in a 
> 204 response?

That's correct, meaning the restriction just to return those headers 
classified as "Entity Headers" in RFC2616 would need to be relaxed. That 
shouldn't break anything.

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 4 Apr 2006 12:34:55 -0700

On 2006/04/04, at 12:25 PM, Julian Reschke wrote:

> Mark Nottingham wrote:
>> ...
>> OK. If we were *really* picking apart 2616, I'd think a re-org of  
>> the header classifications would be in order; Jeff M took a stab  
>> at this in "Clarifications of the Fundamentals of HTTP."
>
> The problem is that the group of people interested in this topic (=  
> the readers of this mailing list) do not seem to agree upon whether  
> the spec needs to be clarified, and if it needs to, how to proceed.  
> Every few months we're exchanging a few mails about this topic, but  
> in the end the discussion dies away.

I've heard of this problem before. It's a pity, because the  
classifications in the spec aren't helpful, and occasionally  
misleading. *sigh*

>> explicitly used as a successful non-GET/POST response (both GET  
>> and POST responses can be cacheable). Problem is, 200 is hard- 
>> wired as the code to use in a number of places (e.g., the  
>> definition of PUT).
>> it's necessary to return an entity body with the PUT response? If  
>> the scope of metainformation updates in the definition of 204, or  
>> the definition of entity-headers, can be adjusted just a bit, it  
>> should be adequate, I think. After all, what other possible  
>> meaning could an ETag have in a 204 response?
>
> That's correct, meaning the restriction just to return those  
> headers classified as "Entity Headers" in RFC2616 would need to be  
> relaxed. That shouldn't break anything.

Works for me.

--
Mark Nottingham
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Mon, 10 Apr 2006 17:34:00 +0200

Mark Nottingham wrote:
>> (<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.7.1>) but 
>> a Response Header 

So, summarizing: I think we can state that RFC2616 already says that an 
Etag response header in PUT is for the *requested variant*, not the 
enclosed entity body. Thus, I'd like to rephrase my recommendation to say:

5.1.  Julian's suggestion

    This proposal is based on the assumptions below:

    o  Clients can not assume that servers do not rewrite content sent
       with PUT.

    o  Furthermore, clients can not assume that an ETag they may be
       getting in a PUT response can be used as cache validator in a
       subsequent GET.

    o  We don't want to break existing servers.

    o  Any extension we come up with should be as simple as possible,
       making it more likely to be implemented.

    Thus proposing the following extensions/clarifications:

    o  Clarify the language [RFC2616] about the meaning of ETag headers
       in 2xx responses, such as in <http://lists.w3.org/Archives/Public/
       ietf-http-wg/2006JanMar/0003.html>.

    o  Clarify that servers may return a new ETag for any method that may
       affect the requested variant (such as a PROPPATCH that rewrites
       the content of the resource).

    o  Optionally, add a new response header through which a server can
       indicate that it has indeed stored the submitted entity byte-by-
       byte (this is a simplified variant of Jim Whitehead's proposal
       that would give the client control about what kind of content
       rewriting is allowed).

Best regards, Julian