Opened 7 years ago

Closed 7 years ago

#419 closed editorial (incorporated)

p2 editorial feedback

Reported by: mnot@… Owned by: fielding@…
Priority: normal Milestone: 22
Component: p2-semantics Severity: In WG Last Call
Keywords: Cc:

Description

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

Change History (26)

comment:1 Changed 7 years ago by mnot@…

From [2013]:

Clean up Changes from RFC2616; partially addresses #419.

comment:2 Changed 7 years ago by fielding@…

From [2043]:

make some sections headers plural; partly addresses #419

comment:3 Changed 7 years ago by fielding@…

From [2046]:

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

comment:4 Changed 7 years ago by fielding@…

From [2047]:

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

comment:5 Changed 7 years ago by mnot@…

  • Owner changed from draft-ietf-httpbis-p2-semantics@… to fielding@…

comment:6 Changed 7 years ago by fielding@…

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]

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

comment:7 Changed 7 years ago by fielding@…

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.

comment:8 Changed 7 years ago by fielding@…

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

comment:9 Changed 7 years ago by fielding@…

From [2051]:

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

comment:10 Changed 7 years ago by fielding@…

From [2052]:

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

comment:11 Changed 7 years ago by fielding@…

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.

comment:12 Changed 7 years ago by fielding@…

From [2054]:

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

comment:13 Changed 7 years ago by fielding@…

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.

comment:14 Changed 7 years ago by fielding@…

From [2055]:

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

comment:15 Changed 7 years ago by fielding@…

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.

comment:16 Changed 7 years ago by fielding@…

From [2056]:

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

comment:17 Changed 7 years ago by fielding@…

From [2057]:

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

comment:18 Changed 7 years ago by fielding@…

From [2058]:

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

comment:19 Changed 7 years ago by fielding@…

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.

comment:20 Changed 7 years ago by fielding@…

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

comment:21 Changed 7 years ago by fielding@…

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.

comment:22 Changed 7 years ago by fielding@…

From [2068]:

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

comment:23 Changed 7 years ago by fielding@…

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.

comment:24 Changed 7 years ago by fielding@…

From [2078]:

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

comment:25 Changed 7 years ago by fielding@…

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

comment:26 Changed 7 years ago by fielding@…

  • Milestone changed from unassigned to 22
  • Resolution set to incorporated
  • Status changed from new to closed

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!

Note: See TracTickets for help on using tickets.