p2 editorial feedback

[mnot]

• Several of the section headers should be pluralised; e.g., "2. Resource" -> "2. Resources"; "3. Representation" -> "3. Representations"; "3.1.1 Data Type" -> "3.1.1 Data Types" (most sections are pluralised, and having a few that aren't is jarring)

• 2. Resource - "Resource owners SHOULD NOT include request semantics within a URI..." This is a new requirement; I personally think it's justified for interop, but wanted to make sure everyone was aware.

• 3.1.1.1 Media Types - references to RFC4288 needs to be updated to draft-ietf-appsawg-media-type-regs.

• 3.1.x - we seem to have a variety of language about respecting the registries; use of non-registered media types is "discouraged", while "Applications SHOULD limit their use of character encodings to those defined within the IANA registry." No such advice is given about Content-Types, while content-codings "SHOULD be registered." Finally, we only note that language tags have a name space "administered by IANA."

I'm not suggesting we have consistency for its own sake here, but it does seem like these are pretty wildly divergent, and I can't see why.

• 3.1.1.3 Canonicalization and Text Defaults -- "... a bare CR or LF MUST NOT be substituted for CRLF within any of the HTTP control structures (such as header fields and multipart boundaries)." At least for header fields, this seems to contradict common practice and the advice for Message Parsing Robustness in p1. This text was also in 2616.

• 3.1.1.4 Multipart Types -- "In all other respects, an HTTP user agent SHOULD follow the same or similar behaviour as a MIME user agent would upon receipt of a multipart type." This is a meaningless SHOULD; suggest "ought to."

• 3.1.1.5 Content Type -- "... defines both the data format and how that data SHOULD be processed by the recipient..." Is this really a conformance requirement? Suggest "ought to."

• 3.1.1.5 Content Type -- "A server SHOULD include a Content-Type header field in a message containing a payload body... unless the intended media type is unknown to the sender." Have we settled on "SHOULD... unless" or "MUST... unless" for this type of construct? I don't want to provoke a religious war, just want a consistent spec.

• 3.1.2.2 Content-Encoding -- The second-to-last paragraph illustrates a situation where content negotiation is taking place; it would be good to mention the need to use Vary as well.

• 3.1.2.2 Content-Encoding -- last paragraph: "The server SHOULD respond with a status code of 415 (Unsupported Media Type)." Here and many other places, we use SHOULD to denote that in normal processing, that status code gets used, but that another status code might pre-empt it (e.g., 401). It would be nice if this were spelled out somewhere and referred to throughout, to make the conditions on the SHOULD unambiguous.

• 3.4.1 Proactive Negotiation -- this revision brings new terms, "proactive negotiation" and "reactive negotiation." This hasn't been discussed on-list, so I wanted to make sure people were aware. Also, it would be nice to refer to the old names (server-driven and client-driven) to help people map from the old spec.

• 3.4.1 Proactive Negotiation -- The note about User-Agent based negotiation implies that it's fragile because new clients might not be recognised. This is only part of the story; it's also fragile because the mapping of capabilities to the UA string is inexact at best. Finally, "clients" should be "user-agents", as other clients don't insert UA.

• 3.4.2 Reactive Negotiation -- The sentence beginning with "In addition, this specification does not define any mechanism..." would read better if it were moved to the end of the last paragraph and adjusted accordingly.

• 4. Product Tokens -- This section is quite awkward here. What about moving it as a subsection of the introduction? Or, moving it to the first place it's used (as has been done with several other constructs)?

• 5.1 Request Methods overview -- Same problem as in 3.1.2.2 WRT status codes and SHOULD (two occurrences)

• 5.2.1 Safe Methods -- "The GET, HEAD, OPTIONS and TRACE request methods are defined to be safe." --> "Of the request methods in this specification, the GET, HEAD, OPTIONS and TRACE methods are defined to be safe."

• 5.2.1 Safe Methods -- "A user agent SHOULD distinguish between safe and unsafe methods when presenting potential actions to a user..." This is a requirement on user interaction -- is it really a conformance requirement?

• 5.3.1 GET -- "... it is the produced data which shall be returned..." -- avoid RFC2119 language; suggest "will"

• 5.3.3 POST -- the list of functions could be read as exclusive; suggest clarifying that these are just examples.

• 5.3.3 POST -- "If a resource has been created on the origin server..." -> "If a resource (or more than one resources) has been created on the origin server..."

• 5.3.4 PUT -- "Unrecognized header fields SHOULD be ignored..." --> "... SHOULD be ignored by the server..."

• 5.3.5 DELETE -- The first paragraph is awkward; it seems like a collection of random statements.

• 5.3.6 CONNECT -- The first paragraph is awkward; it should come out and say that it's intended for proxies, not origin servers.

• 6.5 Context -- the title is quite curt; suggest "Request Context"

• 6.5.1 From -- "The 'From' header field, if given, SHOULD contain an Internet e-mail address..." Why just SHOULD?

• 6.5.1 From -- "In particular, robot agents SHOUDL include this header field..." AIUI this isn't widely adhered to; should we downgrade to prose?

• 6.5.1 From -- "The client SHOULD NOT send the From header field without the user's approval..." Does this need to be a requirement?

• 6.5.3 User-Agent -- "User agents SHOULD include this field with requests." Is this really a conformance requirement?

• 7 Response Status Codes -- "In such cases, user agents SHOULD present to the user the representation enclosed with the response..." Again, a UI requirement; downgrade to prose?

• 7.2.1 100 Continue -- "The client SHOULD continue with its request." SHOULD -> ought to.

• 7.2.1 100 Continue -- "The client SHOULD continue by sending the remainder of the request" --> prose

• 7.2.2 101 Switching Protocols -- "The protocol SHOULD be switched only when it is advantageous to do so." --> prose

• 7.3.2 201 Created -- "If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead." --> prose

• 7.4.1 - 7.6.6 -- Many many SHOULDs that ought to be reformulated as prose.

• 7.5.6 406 Not Acceptable -- "If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions." This is a UI constraint, and even without that consideration, making it a requirement seems quite strong.

8.1.1.2 Date -- "Clients can use the Date header field as well; in order..." --> "Clients can use the Date header field in requests as well; in order..."

• 8.1.2 Location -- "For 3xx (Redirection) responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource." --> prose

• 8.1.2 Location -- Should mention that new status codes MAY define semantics for Location.

• 8.1.2 Retry-After -- Should mention that new status codes MAY nominate the use of Retry-After.

• 8.2.1 Vary -- would benefit greatly from an example of two responses that a resource uses negotiation on (showing with and without gzip, for example).

• 8.2.1 Vary -- "The field-names given are not limited..." "given" is ambiguous; suggest "listed".

• 8.4 Informative -- The section title is quite terse; suggest "Informative Header Fields"

• 9.1.2 Considerations for new methods -- add: "If it is possible to make a request using a new method conditional [ref to p4], this ought to be documented by that method. Likewise, if partial request semantics [ref to p5] are meaningful for a new method, it ought to document this too."

• 10.1 Transfer of Sensitive Information -- "Therefore, applications SHOULD supply as much control over this information as possible..." Is this really a conformance requirement?

• 10.1 Transfer of Sensitive Information -- "Four header fields are worth special mention in this context..." User-Agent needs to be included here.

• 10.2 Encoding Sensitive Information in URIs -- "...it is strongly recommended that the user be able to select..." Recommended is an RFC2119 keyword; suggest "advised."

• 10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol." This is an odd place to bury this; the section title isn't applicable. Suggest moving it to the section defining the Referer header.

• 10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol." Why SHOULD NOT? I.e., what are the cases where they SHOULD? Ought it be a MUST?

• 10.2 Encoding Sensitive Information in URIs -- "Authors of services SHOULD NOT use GET-based forms for the submission of sensitive data..." Is this really a conformance requirement?

• 10.5 Privacy Issues Connect to Accept Header Fields -- "General purpose user agents which provide a high degree of header field configurability SHOULD warn users..." Is this really a conformance requirement?

• Appendix A. Differences between HTTP and MIME -- contains several SHOULDs that don't describe conditions when it's OK to violate, and either aren't really conformance requirements, or seem quite important for interop (thereby arguing for MUST).

• Appendix C. Changes from RFC2616 -- These notes are quite terse, sometimes becoming difficult to read. Suggest rewriting to normalise tense and point of view.

Reported by @mnot, migrated from https://trac.ietf.org/trac/httpbis/ticket/419

[mnot]

@mnot commented:

From 2013:

Clean up Changes from RFC2616; partially addresses #419.

[mnot]

fielding@gbiv.com commented:

From 2043:

make some sections headers plural; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2046:

Reference BCP numbers when informative and not section specific; Note added requirement on URI consistency with method semantics; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2047:

Clean up pseudo normative text regarding use of registered values; partly addresses #419

[mnot]

@mnot changed owner from draft-ietf-httpbis-p2-semantics@tools.ietf.org to fielding@gbiv.com

[mnot]

fielding@gbiv.com commented:

Several of the section headers should be pluralised; e.g., "2. Resource" -> "2. Resources"; "3. Representation" -> "3. Representations"; "3.1.1 Data Type" -> "3.1.1 Data Types" (most sections are pluralised, and having a few that aren't is jarring) 

done in 2046 and 2047

2. Resource - "Resource owners SHOULD NOT include request semantics within a URI..." This is a new requirement; I personally think it's justified for interop, but wanted to make sure everyone was aware. 

done in 2046

3.1.1.1 Media Types - references to RFC4288 needs to be updated to draft-ietf-appsawg-media-type-regs. 

done in 2046 by referring to BCP. RFC editor can update ref if it is done before HTTPbis.

3.1.x - we seem to have a variety of language about respecting the registries; use of non-registered media types is "discouraged", while "Applications SHOULD limit their use of character encodings to those defined within the IANA registry." No such advice is given about Content-Types, while content-codings "SHOULD be registered." Finally, we only note that language tags have a name space "administered by IANA." 

done in 2047

[mnot]

fielding@gbiv.com commented:

3.1.1.3 Canonicalization and Text Defaults -- "... a bare CR or LF MUST NOT be substituted for CRLF within any of the HTTP control structures (such as header fields and multipart boundaries)." At least for header fields, this seems to contradict common practice and the advice for Message Parsing Robustness in p1. This text was also in 2616. 

Okay, rewritten.

3.1.1.4 Multipart Types -- "In all other respects, an HTTP user agent SHOULD follow the same or similar behaviour as a MIME user agent would upon receipt of a multipart type." This is a meaningless SHOULD; suggest "ought to." 

Not implemented in practice anyway, so deleted.

3.1.1.5 Content Type -- "... defines both the data format and how that data SHOULD be processed by the recipient..." Is this really a conformance requirement? Suggest "ought to." 

More of a factual statement depending on message semantics, so rewritten accordingly.

3.1.1.5 Content Type -- "A server SHOULD include a Content-Type header field in a message containing a payload body... unless the intended media type is unknown to the sender." Have we settled on "SHOULD... unless" or "MUST... unless" for this type of construct? I don't want to provoke a religious war, just want a consistent spec. 

I prefer SHOULD in this case, because there might be a reason for the server to want the client to sniff even if the server thinks it knows the type.

3.1.2.2 Content-Encoding -- The second-to-last paragraph illustrates a situation where content negotiation is taking place; it would be good to mention the need to use Vary as well. 

That does not actually refer to URI mapping (they may be different resources) and would obfuscate the point.

3.1.2.2 Content-Encoding -- last paragraph: "The server SHOULD respond with a status code of 415 (Unsupported Media Type)." Here and many other places, we use SHOULD to denote that in normal processing, that status code gets used, but that another status code might pre-empt it (e.g., 401). It would be nice if this were spelled out somewhere and referred to throughout, to make the conditions on the SHOULD unambiguous. 

In this case it should be a MAY, and also needs to be reflected in definition of 415. Done.

3.4.1 Proactive Negotiation -- this revision brings new terms, "proactive negotiation" and "reactive negotiation." This hasn't been discussed on-list, so I wanted to make sure people were aware. Also, it would be nice to refer to the old names (server-driven and client-driven) to help people map from the old spec. 

Okay.

3.4.1 Proactive Negotiation -- The note about User-Agent based negotiation implies that it's fragile because new clients might not be recognised. This is only part of the story; it's also fragile because the mapping of capabilities to the UA string is inexact at best. Finally, "clients" should be "user-agents", as other clients don't insert UA. 

OBE.

3.4.2 Reactive Negotiation -- The sentence beginning with "In addition, this specification does not define any mechanism..." would read better if it were moved to the end of the last paragraph and adjusted accordingly. 

It works better as a last para. The previous last para has moved up to mid section.

[mnot]

fielding@gbiv.com commented:

4. Product Tokens -- This section is quite awkward here. What about moving it as a subsection of the introduction? Or, moving it to the first place it's used (as has been done with several other constructs)? 

Okay, moved into User-Agent.

6.5 Context -- the title is quite curt; suggest "Request Context" 

Okay.

8.4 Informative -- The section title is quite terse; suggest "Informative Header Fields" 

Now "Response Context"

[mnot]

fielding@gbiv.com commented:

From 2051:

Move product tokens into UA and clean User-Agent and Server definitions; Retitle Context and Informative sections; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2052:

editorial fixes in methods; use send instead of return, sent instead of returned; partly addresses #419

[mnot]

fielding@gbiv.com commented:

5.1 Request Methods overview -- Same problem as in 3.1.2.2 WRT status codes and SHOULD (two occurrences) 

Partly done in 2047, just fixed a few more in 2052.

5.2.1 Safe Methods -- "The GET, HEAD, OPTIONS and TRACE request methods are defined to be safe." --> "Of the request methods in this specification, the GET, HEAD, OPTIONS and TRACE methods are defined to be safe." 

Okay.

5.2.1 Safe Methods -- "A user agent SHOULD distinguish between safe and unsafe methods when presenting potential actions to a user..." This is a requirement on user interaction -- is it really a conformance requirement? 

It is a social requirement, yes.

5.3.1 GET -- "... it is the produced data which shall be returned..." -- avoid RFC2119 language; suggest "will" 

Okay, but may need a larger rewrite.

5.3.3 POST -- the list of functions could be read as exclusive; suggest clarifying that these are just examples.

Okay.

5.3.3 POST -- "If a resource has been created on the origin server..." -> "If a resource (or more than one resources) has been created on the origin server..." 

Okay.

5.3.4 PUT -- "Unrecognized header fields SHOULD be ignored..." --> "... SHOULD be ignored by the server..." 

Okay.

5.3.5 DELETE -- The first paragraph is awkward; it seems like a collection of random statements. 

Rewritten.

5.3.6 CONNECT -- The first paragraph is awkward; it should come out and say that it's intended for proxies, not origin servers. 

Rewritten.

[mnot]

fielding@gbiv.com commented:

From 2054:

improve definition of the From header field; partly addresses #419

[mnot]

fielding@gbiv.com commented:

6.5.1 From -- "The 'From' header field, if given, SHOULD contain an Internet e-mail address..." Why just SHOULD? 

Back in the day, there were still some non-Internet email addresses. I have changed it to just be a fact (contains).

6.5.1 From -- "In particular, robot agents SHOUDL include this header field..." AIUI this isn't widely adhered to; should we downgrade to prose? 

It was widely adhered to the last I checked. If we downgrade, we might as well just deprecate the header.

6.5.1 From -- "The client SHOULD NOT send the From header field without the user's approval..." Does this need to be a requirement? 

Yes, though I have rephrased it.

6.5.3 User-Agent -- "User agents SHOULD include this field with requests." Is this really a conformance requirement? 

Yes, for interoperability -- a lot of sites deny access without it.

[mnot]

fielding@gbiv.com commented:

From 2055:

editorial improvements to 1xx and 2xx status codes; partly addresses #419

[mnot]

fielding@gbiv.com commented:

7 Response Status Codes -- "In such cases, user agents SHOULD present to the user the representation enclosed with the response..." Again, a UI requirement; downgrade to prose? 

Okay.

7.2.1 100 Continue -- "The client SHOULD continue with its request." SHOULD -> ought to.

Okay.

7.2.1 100 Continue -- "The client SHOULD continue by sending the remainder of the request" --> prose

Okay.

7.2.2 101 Switching Protocols -- "The protocol SHOULD be switched only when it is advantageous to do so." --> prose 

Okay.

7.3.2 201 Created -- "If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead." --> prose 

Deleted, redundant.

7.4.1 - 7.6.6 -- Many many SHOULDs that ought to be reformulated as prose.

Oy, done through 2xx.

[mnot]

fielding@gbiv.com commented:

From 2056:

editorial improvements to 3xx status codes; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2057:

editorial improvements to 4xx status codes; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2058:

editorial improvements to 5xx status codes; partly addresses #419

[mnot]

fielding@gbiv.com commented:

7.4.1 - 7.6.6 -- Many many SHOULDs that ought to be reformulated as prose.

Done.

7.5.6 406 Not Acceptable -- "If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions." This is a UI constraint, and even without that consideration, making it a requirement seems quite strong. 

And a bit silly as well -- I removed it in 2057.

8.1.1.2 Date -- "Clients can use the Date header field as well; in order..." --> "Clients can use the Date header field in requests as well; in order..."

Fixed in 2065.

8.1.2 Location -- "For 3xx (Redirection) responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource." --> prose 

Done.

8.1.2 Location -- Should mention that new status codes MAY define semantics for Location. 

That is true of all response header fields. I don't see any reason to repeat it here. I have added it to considerations for new codes and new fields.

8.1.2 Retry-After -- Should mention that new status codes MAY nominate the use of Retry-After.

Ditto.

9.1.2 Considerations for new methods -- add: "If it is possible to make a request using a new method conditional [ref to p4], this ought to be documented by that method. Likewise, if partial request semantics [ref to p5] are meaningful for a new method, it ought to document this too."

Done.

[mnot]

fielding@gbiv.com commented:

From 2067:

(editorial) clarify that header fields are refined by method and status code semantics; more rephrasing to identify subject of requirements; partly addresses #419

[mnot]

fielding@gbiv.com commented:

8.2.1 Vary -- would benefit greatly from an example of two responses that a resource uses negotiation on (showing with and without gzip, for example). 

That is in p4. I'll add a field example.

8.2.1 Vary -- "The field-names given are not limited..." "given" is ambiguous; suggest "listed".

It belongs above that anyway -- rewritten.

[mnot]

fielding@gbiv.com commented:

From 2068:

(editorial) rewrite definition of Vary; partly addresses #419

[mnot]

fielding@gbiv.com commented:

10.1 Transfer of Sensitive Information -- "Therefore, applications SHOULD supply as much control over this information as possible..." Is this really a conformance requirement? 

Fixed.

10.1 Transfer of Sensitive Information -- "Four header fields are worth special mention in this context..." User-Agent needs to be included here. 

Deleted.

10.2 Encoding Sensitive Information in URIs -- "...it is strongly recommended that the user be able to select..." Recommended is an RFC2119 keyword; suggest "advised."

Fixed.

10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol." This is an odd place to bury this; the section title isn't applicable. Suggest moving it to the section defining the Referer header. 

Done in 2072.

10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol." Why SHOULD NOT? I.e., what are the cases where they SHOULD? Ought it be a MUST? 

Done in 2072.

10.2 Encoding Sensitive Information in URIs -- "Authors of services SHOULD NOT use GET-based forms for the submission of sensitive data..." Is this really a conformance requirement? 

Fixed.

10.5 Privacy Issues Connect to Accept Header Fields -- "General purpose user agents which provide a high degree of header field configurability SHOULD warn users..." Is this really a conformance requirement? 

Fixed.

[mnot]

fielding@gbiv.com commented:

From 2078:

(editorial) rearrange CONNECT and rewrite Security Considerations; partly addresses #419

[mnot]

fielding@gbiv.com commented:

From 2083:

Requirements are not allowed in appendices. They have been changed to prose. Changes from RFC2616 have been rewritten for consistency and to remove changes that are only editorial. Addresses #419

[mnot]

• fielding@gbiv.com commented:

Appendix A. Differences between HTTP and MIME -- contains several SHOULDs that don't describe conditions when it's OK to violate, and either aren't really conformance requirements, or seem quite important for interop (thereby arguing for MUST). 

No requirements are allowed in appendices. They have been changed to prose.

Appendix C. Changes from RFC2616 -- These notes are quite terse, sometimes becoming difficult to read. Suggest rewriting to normalise tense and point of view.

Done!

• fielding@gbiv.com changed milestone from unassigned to 22
• fielding@gbiv.com changed resolution to incorporated
• fielding@gbiv.com changed status from new to closed