Subject: Defining the meaning of headers associated with a request body

From: Duncan Cragg <[email-masked]>
Date: Wed, 18 Jan 2012 15:51:17 +0000

I'm not certain of the protocol here, so if it's OK I'll just wade in 
and hope for the
best...

I'd like to know if http-bis will tighten up the meanings of various 
headers on a
request that contains a body: POST and PUT in particular. I'm wondering 
how they will
compare to their meaning on a GET /response/.

Example
-------

For example, consider this GET response:

  GET /x HTTP/1.1

  HTTP/1.1 200 OK
  Content-Type: text/plain
  Content-Length: 100
  Cache-Control: max-age=3600
  Etag: "1"
  Content-Location: http://foo.com/y

  ..

Now suppose I had this very similar request with a body on a POST or a PUT:

  POST|PUT /z HTTP/1.1
  Content-Type: text/plain
  Content-Length: 100
  Cache-Control: max-age=3600
  Etag: "1"
  Content-Location: http://foo.com/y

  ..

Clearly, Content-Type and Content-Length are fine, and mean exactly the 
same as on the
GET response. But what of Cache-Control, Etag and Content-Location?

Note that I'm not considering the meaning of the target (/z, here). I'm 
assuming only
that someone has a valid reason to want to tie up the metadata to its 
entity, for either
PUT or POST. Maybe I want to notify via POST an indexer at /z that there 
is an interesting
resource at http://foo.com/y , which had an Etag of "1" and TTL of 3600 
when I fetched it?

RFC2616
-------

The current spec says, for PUT, there is 'Must-Understand' on all 
Content-* headers, and
that 'entity-headers in the PUT request SHOULD be applied to the 
resource created or
modified by the PUT'.

Thus it gives hope of interpreting a sensible meaning for the Expires 
(similar in use to
the max-age), Last-Modified (similar in use to Etag) and 
Content-Location headers, at
least in the context of a PUT request: implying that they are associated 
with the
request entity. POST has nothing similar to say.

Now the Cache-Control on a request normally attempts to effectively 
modify the
Cache-Control of the subsequent response, rather than, as here, being 
intended to
describe the TTL or lifetime of the request entity. Thus it may clash 
for such a use, or,
since there is no real need for the existing meaning for PUT and POST, 
it could be
specified as applying to the request entity in particular for those 
methods, especially
since we may interpret the old Expires this way.

Similarly, we are allowed to suggest a Last-Modified header value, but 
not an Etag,
which has a different, non-entity or 'response-header' status, even 
though used in a
very similar way.

Finally, we have: "The meaning of the Content-Location header in PUT or 
POST requests is
undefined; servers are free to ignore it in those cases." Which is slightly
contradictory to the hope offered by the preceding text!

Bis
---

I'm not going to pretend I've deeply read and tracked the work here - 
it's a full-time
job, I'm sure. I tried to find relevant material, though.

Here, for PUT, we have 'Unrecognized header fields SHOULD be ignored 
(i.e., not saved as
part of the resource state).' A superficial skim indicates that much of 
the above wording
has been removed. Tickets 79 & 102 seem to be related. So it seems to be 
less clear than
before that we can associate such headers this way?

Or are we now more free, to decide to 'recognize header fields and save 
them with the
resource state'? Which ones?

Here's more on Content-Location on requests (presumably either PUT or 
POST, although the
comment is specifically about trying to manipulate PUT):

    .. Content-Location .. MAY be
    interpreted by the origin server as an indication of where the user
    agent originally obtained the content of the enclosed representation
    .. the Content-Location
    cannot be used as a form of reverse content selection that identifies
    only one of the negotiated representations to be updated...

Which seems fine. But sadly:

    A Content-Location field received in a request message is transitory
    information that SHOULD NOT be saved with other representation
    metadata for use in later responses.  The Content-Location's value
    might be saved for use in other contexts, such as within source links
    or other metadata.

I don't understand 'source links or other metadata', however. Perhaps 
some extra wording
would help future readers? Maybe we can still submit something using 
POST to our indexer?

Summary
-------

So there is some information in the RFC and in Bis, but it isn't a 
complete or, to me,
very clear set, particularly around decoration of POST bodies/entities 
with metadata.

What do the core of this list think about all this?

Cheers!

Duncan Cragg

---

From: Zhong Yu <[email-masked]>
Date: Wed, 18 Jan 2012 12:57:35 -0600

The categorization of headers is indeed very confusing; here's my take
(not an expert)

Content-Length/Transfer-Encoding
    request and response

Content-Range
    request and response

    However, HTTP/1.1 only really described it for responses to GET requests.
    its meaning in other contexts is unclear.

Content-Encoding
    request and response

    However, there's no official way for client to know what encoding is
    acceptable by server; a request with Content-Encoding is risky.

Content-Type
    request and response

ETag
    response only.
    (It applies to the representation/entity, not the response)

Expires
    response only;
    and it applies to the response! not the representation/entity.

Last-Modified
    response only;
    applies to the representation/entity

Content_Location
    request and response
    However, it doesn't seem to be very useful in requests

Content_Language
    request and response
    However, usage of Content-Language in requests is not elaborated.

So basically, only headers that are appropriate in requests are
Content-Length/Transfer-Encoding, Content-Type.

Zhong Yu

---

From: Karl Dubost <[email-masked]>
Date: Wed, 18 Jan 2012 14:43:56 -0500

A long long long time ago, when elves were still existing, there was a nice page about 

HTTP headers for Request 
http://www.w3.org/Protocols/HTTP/HTRQ_Headers.html

HTTP headers for Response
http://www.w3.org/Protocols/HTTP/Object_Headers.html

In a more recent document ;) this still exists

3.2.  Request Header Fields
http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-18#section-3.2

3.3.  Response Header Fields
http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-18#section-3.3

PS: /me loves the "Cost:" header. :)
http://www.w3.org/Protocols/HTTP/Object_Headers.html#cost

-- 
Karl Dubost - http://dev.opera.com/
Developer Relations, Opera Software

---

From: Zhong Yu <[email-masked]>
Date: Wed, 18 Jan 2012 14:19:59 -0600

> http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-18#section-3.3

But they are not very consistent. For example, how come Expires is a
representation header, not a response header, while ETag is a response
header, not a representation header?

> http://www.w3.org/Protocols/HTTP/Object_Headers.html#cost

We still have 402 Payment Required :)

---

From: Amos Jeffries <[email-masked]>
Date: Thu, 19 Jan 2012 11:46:15 +1300

>     (It applies to the representation/entity, not the response)

This may make sense opening to PUT requests. Since PUT is based 
semantically around some resource at either client or server end.
POST would seem to have less use since its entity is more ephemeral.

We get a re-occuring question of how to cache POST bodies.

With PUT having ETag and Content-Location middleware could use the 2xx 
response as an indicator that the PUT entity is at Content-Location and 
can work on caching Location+Etag without needing some future backend 
200 response to fetch it first (re-validate would still be needed to get 
the expiry info, but that is small 304).

>     However, usage of Content-Language in requests is not elaborated.

Applies to the representation. So is of some small use where there is 
language-specific entity data for at least PUT, POST and WebDAV editing 
extension methods.

---

From: Duncan Cragg <[email-masked]>
Date: Fri, 20 Jan 2012 09:36:55 +0000

Thanks for the replies so far .. lots of very interesting information in 
there.

My original question remains, however, so I'm wondering if I'm just 
missing something about the nature of HTTP headers...

Allow me to cut right down to the essentials of my question:

  POST /z HTTP/1.1

My question is: /what do those three headers mean/ ??

If they mean 'nothing', does that allow me to correctly set up an agreed 
protocol wherein they mean 'associated with the POSTed body/entity'?

 From combinations of RFC2616 and Bis, I get that:

  - Cache-Control is/was a 'general header', although registered 
alongside the 'entity header', Expires, in p6.
  - Etag is a 'response header', although registered alongside the 
'entity header', Last-Modified, in p4.
  - Content-Location is/was an 'entity header'.

(The phrases 'entity' and 'general' appear to be dropped since ticket 224.)

Perhaps there would be value in constructing a single table with all the 
headers, what category they are (request, response, other??), what they 
mean in requests (GET/P*), what in responses?

Saying 'in this context, this header means nothing as far as Bis is 
concerned, so use it as you like' would be quite valuable information in 
general, where it holds true.

Cheers!

Duncan

---

From: Amos Jeffries <[email-masked]>
Date: Sat, 21 Jan 2012 23:51:34 +1300

On 20/01/2012 10:36 p.m., Duncan Cragg wrote:
> Thanks for the replies so far .. lots of very interesting information 
> in there.
>

Cache-Control: max-age=3600    ==> the reply to this POST must not be an 
object older than 3600 seconds.
    http://tools.ietf.org/html/draft-ietf-httpbis-p6-cache-18#section-3.2.1

ETag: "1"   ==> the body object of this request has a unique identifier 
"1". The new spec does *not* limit it to one of request or reply.
   
http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-18#section-2.3

Content-Location: http://foo.com/y   ==> a GET request of this URL would 
produce identical object for response body as this POST request body.
    http://tools.ietf.org/html/draft-ietf-httpbis-p3-payload-18#section-6.7

"  if one were to perform a GET on this URI at the time of
    this message's generation, then a 200 response would contain the same
    representation that is enclosed as payload in this message.

"

> If they mean 'nothing', does that allow me to correctly set up an 
> agreed protocol wherein they mean 'associated with the POSTed 
> body/entity'?

Ignoring because you started with "If" and its condition was false.

> alongside the 'entity header', Expires, in p6.

Was. As you note below the definition was dropped. It is about controls 
on the cache handling. Which implies the response, but is not so limited 
base on the header name alone. The option values are where scope for 
particular request/response usage and other things like entity comes 
into play.

> 'entity header', Last-Modified, in p4.

The response limitation has been removed. It simply means the entity 
representation now. It is a coincidence that most requests have no body 
entity for it to be useful with today.

>  - Content-Location is/was an 'entity header'.

Still is. see above.

> Perhaps there would be value in constructing a single table with all 
> the headers, what category they are (request, response, other??), what 
> they mean in requests (GET/P*), what in responses?

As I understand it the headers have been split into groups along feature 
boundaries. The groups being:  messaging, semantics, payload 
(entity/representation), conditional, cache, range, and authentication. 
Each of the draft document outlines and defines the headers which are in 
that group, splitting them by request and reply sub-groups and 
tabularizes the headers as part of the RFC index.

So where would one put a re-joined table? and what use would it be for 
those who care only about one particular sub-group of headers?

> concerned, so use it as you like' would be quite valuable information 
> in general, where it holds true.
>

The editors have been doing exactly that AFAICS, whenever consensus here 
found that it was important to state something was useless. Just because 
we have no use for things *yet*, does not make them permanently 
meaningless. Also as has been mentioned before writing down everything 
which is *not* useful is a unimaginably huge amount text to wade through 
for a few small nuggets about when it *is* useful.

AYJ