Hi James,
see below for my (mostly editorial) feedback:
Multiple times: s/header/header field/
1. Introduction
Within the course of processing an HTTP request there are typically a
range of required and optional behaviors that a server or
intermediary can employ. These often manifest is a variety of subtle
and not-so-subtle ways within the response.
s/is/in/
For example, when using the HTTP PUT method to modify a resource --
similar to that defined for the Atom Publishing Protocol [RFC 5023]
reference to RFC 5023 is missing
The rigid, must-understand semantics of the Expect header, therefore,
make it a poor choice for the general expression of optional
preferences that may be specific to an individual application and are
therefore unknown to an intermediary or are otherwise irrelevant to
the intermediaries successful handling of the request and response.
Another option available to clients is to utilize Request URI query-
string parameters to express preferences. Doing so, however, results
in a variety of issues affecting the cacheability of responses.
Comment: not according to the spec; but there are other issues with it,
such as overloading the URI namespace.
As an alternative, this specification defines a new HTTP request
header field that can be used by clients to request that optional
behaviors be applied by a server during the processing the request.
Additionally, a handful of initial preference tokens for use with the
new header are defined.
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in [RFC2119].
ID-Nits complained it couldn't find this note. It probably needs some
adjustment.
1.1. Syntax Notation
This specification uses the Augmented Backus-Naur Form (ABNF)
notation of [RFC5234] and includes, by reference, the "token",
"word", "OWS", "BWS" rules and the #rule extension as defined within
Sections 1.2 and 3.2.4 of [I-D.ietf-httpbis-p1-messaging].
Note: need to re-check the section numbers, they might have moved.
2. The Prefer Request Header Field
The Prefer request-header field is used to indicate that particular
server behaviors are preferred by the client, but not required for
successful completion of the request. Prefer is similar in nature to
the Expect header field defined by Section 9.3 of
[I-D.ietf-httpbis-p2-semantics] with the exception that servers are
Ditto.
If a particular preference token or parameter is specified multiple
times, repeated occurrences MUST be ignored without signaling an
error or otherwise altering the processing of the request.
That means: first wins, right? The repeated occurrences might have
different parameters...
The Prefer request header field is end-to-end and MUST be forwarded
by a proxy if the request is forwarded.
That's something *this* spec can not require; it should follow from
HTTPbis, right?
s/header/header field/
No significance is given to the order in which preference tokens
appear within a request.
Really? What if a token is repeated with different parameters?
2.1. Content Negotiation and Cache Considerations
Note that while the Prefer header field is not intended to be used as
content negotiation mechanism, the application of a preference
potentially could affect the caching characteristics of a response.
Specifically, if a server supports the optional application of a
preference that could even just potentially result in a variance to a
cache's handling of a response entity, a Vary header field MUST be
included with the response listing the Prefer header field regardless
of whether the client actually used Prefer in the request.
Because of the inherent complexities involved with properly
implementing server-driven content negotiation, effective caching,
and the application of optional preferences, implementors must
...avoid lowercase RFC2119 keywords...
exercise caution when utilizing preferences in such a way as to
impact the caching of a response and SHOULD NOT use the Prefer header
mechanism for content negotiation.
2.2. Examples
The following examples illustrate the use of various preferences
defined by this specification, as well as undefined extensions for
strictly illustrative purposes:
1. Return a "202 Accepted" response for asynchronous processing if
the response cannot be processed within 10 seconds. An undefined
"priority" preference is also specified:
Prefer: return-asynch, wait=10;
Prefer: priority=5;
Shouldn't that be:
Prefer: return-asynch; wait=10
Prefer: priority=5
???
3. Preference Definitions
The following subsections define an initial set of preferences.
Additional preferences can be registered for convenience and/or to
promote reuse by other applications. This specification establishes
an IANA registry of such relation types (see Section 4.1).
Registered preference names MUST conform to the token rule, and MUST
be compared character-by-character in a case-insensitive fashion.
They SHOULD be appropriate to the specificity of the preference;
i.e., if the semantics are highly specific to a particular
application, the name should reflect that, so that more general names
remain available for less specific use.
Registered preferences MUST NOT constrain servers, clients or any
intermediaries involved in the exchange and processing of a request
to any behavior required for successful processing. The use and
application of a preference within a given request MUST be optional
on the part of all participants.
3.1. The "return-asynch" Preference
The "return-asynch" preference indicates that the client prefers the
server to respond asynchronously to a response. For instance, in the
case when the length of time it takes to generate a response will
exceed some arbitrary threshold established by the server, the server
can honor the return-asynch preference by returning either a "202
Accepted" or "303 See Other" response.
...would be good to explain when to use what (not sure about when 303
would be right).
3.4. The "wait" Preference
The "wait" preference can be used to establish an upper bound on the
length of time, in seconds, the client is willing to wait for a
response, after which the client might choose to abandon the request.
In the case generating a response will take longer than the time
specified, the server, or proxy, MAY choose to utilize an
asynchronous processing model by returning, for example, "202
Accepted" or "303 See Other" responses.
ABNF:
wait = "wait" BWS "=" BWS delta-seconds
Clients specifying the "wait" preference SHOULD also use the Date
header field, as specified in Section 9.2 of
[I-D.ietf-httpbis-p2-semantics], within the request to establish the
time at which the client began waiting for the completion of the
request. Failing to include a Date header field in the request would
require the server to use the instant it received or began processing
the request as the baseline for determining how long the client has
been waiting which could yield unintended results.
I'm not totally convinced that taking the Date request header field into
account is necessary given the additional complexity; what do others
think?
3.5. The "strict" and "lenient" Processing Preferences
Editorial: why are "strict" and "lenient" described in a single section,
while "return-representation" and "return-minimal" are not?
An example request specifying the "strict" preference:
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: strict
An example request specifying the "lenient" preference:
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: lenient
I like examples, but too much is too much :-)
4. IANA Considerations
The 'Prefer' header field should be added to the Permanent Message
Header Fields registry defined in [RFC3864]
(http://www.iana.org/assignments/message-headers/perm-headers.html).
Header field name: Prefer
Applicable Protocol: HTTP
Status:
"standard", right?
5. Security Considerations
Specific preferences requested by a client can introduce security
considerations and concerns beyond those discussed in HTTP/1.1 Parts
1 [I-D.ietf-httpbis-p1-messaging], 2 [I-D.ietf-httpbis-p2-semantics],
3 [I-D.ietf-httpbis-p3-payload], 4 [I-D.ietf-httpbis-p4-conditional],
There is no spoon^h^h^h^h^hPart 3.
5 [I-D.ietf-httpbis-p5-range], 6 [I-D.ietf-httpbis-p6-cache], and 7
[I-D.ietf-httpbis-p7-auth]. Implementors must refer to the
specifications and descriptions of each preference to determine the
security considerations relevant to each.
Best regards, Julian