WGLC review of p4-19

I believe these are editorial.


* 1. Introduction - The first two paragraphs need to be rewritten for clarity. Suggest:

"""
This specification defines the HTTP/1.1 conditional request mechanisms, consisting of metadata for indicating and observing changes in resource representations, and request header fields that make requests conditional on the state of that metadata. 

There are two primary use cases for conditional requests:

 * They are an efficient way to update cached responses to GET and HEAD requests. This is called "validation", and its effects on caches are defined in [ref to [p6 section 2.4].

 * They can also be used in unsafe requests (e.g., PUT and DELETE) to prevent the "lost update" problem of one client accidentally overwriting the work of another [ref to w3c lost update note]. This is called a "precondition".
"""

... with appropriate changes throughout to make the use of terminology. I.e., The general mechanism defined here is "conditional requests"; when used to validate, it's "validation"; when used to prevent lost update, it's "precondition." I'm happy to discuss other approaches to terminology, I just think it's pretty broken now -- it's not internally self-consistent, and it isn't consistent with p6 (one of the major uses of p4) either.

* 1. Introduction - p6 also uses "selected representation," but with a different meaning. We need to sort this out. 

* 2. Validators - The first paragraph is awkward, and has unnecessary information. Suggest:

"""
Validators are metadata that can be used to observe resource state and impose preconditions upon requests. This specification defines two kinds of validators, modification dates and opaque entity tags. 
"""

* 2.1 Weak vs. Strong - "Rather than impose that all forms of resource adhere to the same strength of validator, HTTP exposes the type of validator in use and imposes restrictions on when weak validators can be used as preconditions." --> "HTTP allows resources to choose a weak or strong validator, based upon their individual requirements and circumstances."

* 2.1 Weak vs. Strong - "...changed to a new, previously unused or guaranteed unique, value..." --> "...changed to a new (previously unused or guaranteed unique) value..."

* 2.1 Weak vs. Strong - "A strong validator MAY be changed for other reasons, such as when a semantically significant part of the representation metadata is changed (e.g., Content-Type), but it is in the best interests of the origin server to only change the value when it is necessary to invalidate the stored responses held by remote caches and authoring tools."   The MAY here is somewhat jarring; I'd think that when the Content-Type changes, it SHOULD or even MUST change. 

* 2.1 Weak vs. Strong - There is a fair amount of duplication between the second and third paragraphs; they should be rewritten (and perhaps combined).

* 2.1 Weak vs. Strong - "...each change to a representation always results in a unique node name and revision identifier..." -- why are we talking about "node names" here? This paragraph seems specific to ETags, and should probably move down there (or just be deleted, as much of the information is repeated in 2.3.1).

* 2.1 Weak vs. Strong - 'A "use" of a validator occurs when...'  Do we really need to air quote 'use' here? I'm not sure what this paragraph is really doing.

* 2.2 Last-Modified - this section and its descendants should use the phrases "modification date" and "Last-Modified value" consistently (as appropriate).

* 2.2.1 Generation - The first paragraph should also mention the use of LM as the default basis for heuristic freshness.

* 2.2.1 Generation - "A representation is typically the sum of many parts behind the resource interface." This is awkward; suggest removing this sentence and changing the next to: "The modification date for a representation is the most recent time that any component of the representation changed."

* 2.2.1 Generation - "An origin server SHOULD obtain the Last-Modified value..." --> "An origin server SHOULD generate the Last-Modified value..."

* 2.2.1 Generation - "...later than the server's time of message origination (Date)." --> "later than the message origination time (as carried in the Date header)."

* 2.2.1 Generation - "... unless these values were associated with the resource by some other system or user with a reliable clock."  This clause is redundant, and can be struck, because the origin server wouldn't be assigning such values anyway.

* 2.2.2 Comparison - I note that this text hasn't changed from RFC2616 much. I think it'd be useful to separate out the comparison methods that can only take place on the origin server (the first one listed) and those that can take place on a client (the others).

* 2.3.3 Example: entity-tags varying on Content-Negotiated Resources - Is there any particular reason why "Hello World!" is repeated so many times? Isn't once sufficient?

* 2.4 Rules for When to Use Entity-tags and Last-Modified Dates - both the section title and first paragraph are somewhat pompous in tone.

* 2.4 Rules... - This section introduces the term "cache-conditional" somewhat casually.  Suggest using 'validating' or 'validation' as appropriate.

* 2.4 Rules... - "In those rare cases where the use of a Last-Modified value as a validator by an HTTP/1.0 system could result in a serious problem, then HTTP/1.1 origin servers should not provide one." This is ill-defined, scary and probably obsolete. Suggest dropping.

* 3 Precondition Header Fields - Note that title should be "Conditional Header Fields" as per above.

3.1 If-Match - Downgrade the MAY to a "can".

3.1 If-Match - "resource update requests" --> "requests that update resources"

3.1 If-Match - "Instead, the server MUST response with the 412 (Precondition Failed) status code." -- I think this should be a SHOULD NOT, so that servers can do things like 401, 403, etc. Also, if p4 is optional, we can't make a requirement here.

3.1 If-Match - the last paragraph should be moved above the example.

3.2 If-None-Match - Downgrade the MAYs to "can"s.

3.2 If-None-Match - the last paragraph should be moved above the example.

3.3 If-Modified-Since - Downgrade the MAY to a "can".

3.3 If-Modified-Since - "as detailed below" is awkward; it should be spelled out here.

3.3 If-Modified-Since - The algorithm packs multiple decisions into steps; it should be expanded to simplify. E.g., the first step is two; checking for validity and checking for 200.

3.3 If-Modified-Since - has too many notes, they should be rewritten as prose.

3.4 If-Unmodified-Since - Downgrade the MAY to a "can".

3.4 If-Unmodifed-Since - "...MUST instead respond with the 412 (Precondition Failed) status code." -- I think this should be a SHOULD NOT, so that servers can do things like 401, 403, etc. Also, if p4 is optional, we can't make a requirement here.

4.1 304 Not Modified - needs to reference p6, probably in the 4th para.


 

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

Received on Friday, 16 March 2012 08:53:14 UTC