< draft-snell-http-prefer-15.txt   draft-snell-http-prefer-16.txt >
Network Working Group J. Snell Network Working Group J. Snell
Internet-Draft October 12, 2012 Internet-Draft October 24, 2012
Intended status: Standards Track Intended status: Standards Track
Expires: April 15, 2013 Expires: April 27, 2013
Prefer Header for HTTP Prefer Header for HTTP
draft-snell-http-prefer-15 draft-snell-http-prefer-16
Abstract Abstract
This specification defines an HTTP header field that can be used by a This specification defines an HTTP header field that can be used by a
client to request that certain behaviors be employed by a server client to request that certain behaviors be employed by a server
while processing a request. while processing a request.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 15, 2013. This Internet-Draft will expire on April 27, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 13
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4
2. The Prefer Request Header Field . . . . . . . . . . . . . . . 4 2. The Prefer Request Header Field . . . . . . . . . . . . . . . 4
2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. The Preference-Applied Response Header Field . . . . . . . . . 7 3. The Preference-Applied Response Header Field . . . . . . . . . 7
4. Preference Definitions . . . . . . . . . . . . . . . . . . . . 8 4. Preference Definitions . . . . . . . . . . . . . . . . . . . . 8
4.1. The "return-asynch" Preference . . . . . . . . . . . . . . 8 4.1. The "respond-async" Preference . . . . . . . . . . . . . . 8
4.2. The "return-representation" and "return-minimal" 4.2. The "return=representation" and "return=minimal"
Preferences . . . . . . . . . . . . . . . . . . . . . . . 9 Preferences . . . . . . . . . . . . . . . . . . . . . . . 9
4.3. The "wait" Preference . . . . . . . . . . . . . . . . . . 11 4.3. The "wait" Preference . . . . . . . . . . . . . . . . . . 11
4.4. The "strict" and "lenient" Processing Preferences . . . . 12 4.4. The "handling=strict" and "handling=lenient"
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 Processing Preferences . . . . . . . . . . . . . . . . . . 12
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
5.1. The Registry of Preferences . . . . . . . . . . . . . . . 13 5.1. The Registry of Preferences . . . . . . . . . . . . . . . 13
5.2. Initial Registry Contents . . . . . . . . . . . . . . . . 14 5.2. Initial Registry Contents . . . . . . . . . . . . . . . . 14
6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1. Normative References . . . . . . . . . . . . . . . . . . . 15 7.1. Normative References . . . . . . . . . . . . . . . . . . . 15
7.2. Informative References . . . . . . . . . . . . . . . . . . 15 7.2. Informative References . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
Within the course of processing an HTTP request there are typically a Within the course of processing an HTTP request there are typically a
range of required and optional behaviors that a server or range of required and optional behaviors that a server or
intermediary can employ. These often manifest in a variety of subtle intermediary can employ. These often manifest in a variety of subtle
and not-so-subtle ways within the response. and not-so-subtle ways within the response.
For example, when using the HTTP PUT method to modify a resource -- For example, when using the HTTP PUT method to modify a resource --
skipping to change at page 5, line 9 skipping to change at page 5, line 9
This header field is defined with an extensible syntax to allow for This header field is defined with an extensible syntax to allow for
future values included in the Registry of Preferences (Section 5.1). future values included in the Registry of Preferences (Section 5.1).
A server that does not recognize or is unable to comply with A server that does not recognize or is unable to comply with
particular preference tokens in the Prefer header field of a request particular preference tokens in the Prefer header field of a request
MUST ignore those tokens and continue processing instead of MUST ignore those tokens and continue processing instead of
signalling an error. signalling an error.
A preference token can contain a value. Empty, or zero length values A preference token can contain a value. Empty, or zero length values
on both the preference token and within parameters are equivalent to on both the preference token and within parameters are equivalent to
no value being specified at all. The following, then, are no value being specified at all. The following, then, are equivalent
equivalent: examples of a "foo" preference with a single "bar" parameter.
Prefer: foo; bar Prefer: foo; bar
Prefer: foo; bar="" Prefer: foo; bar=""
Prefer: foo=""; bar Prefer: foo=""; bar
An optional set of parameters can be specified for any preference An optional set of parameters can be specified for any preference
token. The meaning and application of such parameters is dependent token. The meaning and application of such parameters is dependent
on the definition of each preference token and the server's on the definition of each preference token and the server's
implementation thereof. implementation thereof. There is no significance given to the
ordering of parameters on any given preference.
Comparison of preference token names is case-insensitive while values For both preference token names and parameter names, comparison is
are case-sensitive regardless of whether token or quoted-string case-insensitive while values are case-sensitive regardless of
values are used. whether token or quoted-string values are used.
The Prefer header field is end-to-end and SHOULD be forwarded by a The Prefer header field is end-to-end and MUST be forwarded by a
proxy if the request is forwarded unless Prefer is explicitly proxy if the request is forwarded unless Prefer is explicitly
identified as being hop-by-hop using the Connection header field identified as being hop-by-hop using the Connection header field
defined by [I-D.ietf-httpbis-p1-messaging], Section 6.1. defined by [I-D.ietf-httpbis-p1-messaging], Section 6.1.
In various situations, a proxy might determine that it is capable of In various situations, a proxy might determine that it is capable of
honoring a preference independently of the server to which the honoring a preference independently of the server to which the
request has been directed. For instance, an intervening proxy might request has been directed. For instance, an intervening proxy might
be capable of providing asynchronous handling of a request using 202 be capable of providing asynchronous handling of a request using 202
Accepted responses independently of the origin server. Such proxies Accepted responses independently of the origin server. Such proxies
can choose to honor the "return-asynch" preference on their own can choose to honor the "respond-async" preference on their own
despite whether the origin is capable or willing to do so. despite whether the origin is capable or willing to do so.
Individual preference tokens MAY define their own requirements and Individual preference tokens MAY define their own requirements and
restrictions as to whether and how intermediaries can apply the restrictions as to whether and how intermediaries can apply the
preference to a request independently of the origin server. preference to a request independently of the origin server.
Implementations MUST support multiple instances of the Prefer header A client MAY use multiple instances of the Prefer header field in a
field in a single message, as well as multiple preference tokens single message, or it MAY use a single Prefer header field with
separated by commas in a single Prefer header field. The following multiple comma-separated preference tokens. If multiple Prefer
examples are equivalent: header fields are used, it is equivalent to a single Prefer header
filed with the comma-separated concatentation of all of the tokens.
For example, the following are equivalent:
Multiple Prefer Header Fields: Multiple Prefer header fields defining three distinct preference
tokens:
POST /foo HTTP/1.1 POST /foo HTTP/1.1
Host: example.org Host: example.org
Prefer: return-asynch Prefer: respond-async, wait=100
Prefer: wait=100 Prefer: handling=lenient
Date: Tue, 20 Dec 2011 12:34:56 GMT Date: Tue, 20 Dec 2011 12:34:56 GMT
Single Prefer Header Field: A single Prefer header field defining the same three preference
tokens:
POST /foo HTTP/1.1 POST /foo HTTP/1.1
Host: example.org Host: example.org
Prefer: wait=100, return-asynch Prefer: handling=lenient, wait=100, respond-async
Date: Tue, 20 Dec 2011 12:34:56 GMT Date: Tue, 20 Dec 2011 12:34:56 GMT
To avoid possible ambiguity, individual preference tokens SHOULD NOT To avoid any possible ambiguity, individual preference tokens SHOULD
appear multiple times within a single request. If any preference is NOT appear multiple times within a single request. If any preference
specified more than once, only the first instance is to be is specified more than once, only the first instance is to be
considered. All subsequent occurrences SHOULD be ignored without considered. All subsequent occurrences SHOULD be ignored without
signaling an error or otherwise altering the processing of the signaling an error or otherwise altering the processing of the
request. This is the only case in which the ordering of preferences request. This is the only case in which the ordering of preferences
within a request is considered to be significant. within a request is considered to be significant.
Due to the inherent complexities involved with properly implementing Due to the inherent complexities involved with properly implementing
server-driven content negotiation, effective caching, and the server-driven content negotiation, effective caching, and the
application of optional preferences, implementors are urged to application of optional preferences, implementors are urged to
exercise caution when using preferences in a way that impacts the exercise caution when using preferences in a way that impacts the
caching of a response and SHOULD NOT use the Prefer header mechanism caching of a response and SHOULD NOT use the Prefer header mechanism
for content negotiation. If a server supports the optional for content negotiation. If a server supports the optional
application of a preference that might result in a variance to a application of a preference that might result in a variance to a
cache's handling of a response entity, a Vary header field MUST be cache's handling of a response entity, a Vary header field MUST be
included with the response listing the Prefer header field regardless included in the response listing the Prefer header field regardless
of whether the client actually used Prefer in the request. of whether the client actually used Prefer in the request.
Alternatively, the server MAY include a Vary header with the special
value "*" as defined by [I-D.ietf-httpbis-p2-semantics], Section
8.2.1. Note, however, that use of the "Vary: *" header will make it
impossible for a proxy to cache the response.
2.1. Examples 2.1. Examples
The following examples illustrate the use of various preferences The following examples illustrate the use of various preferences
defined by this specification, as well as undefined extensions for defined by this specification, as well as undefined extensions for
strictly illustrative purposes: strictly illustrative purposes:
1. Return a "202 Accepted" response for asynchronous processing if 1. Return a "202 Accepted" response for asynchronous processing if
the response cannot be processed within 10 seconds. An undefined the request cannot be processed within 10 seconds. An undefined
"priority" preference is also specified: "priority" preference is also specified:
Prefer: return-asynch, wait=10; POST /some-resource HTTP/1.1
Prefer: priority=5; Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
Prefer: priority=5
{...}
2. Use lenient processing: 2. Use lenient processing:
POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient Prefer: Lenient
3. Use of an optional, undefined parameter on the return-minimal {...}
3. Use of an optional, undefined parameter on the return=minimal
preference: preference:
Prefer: return-minimal; foo="some parameter" POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"
{...}
3. The Preference-Applied Response Header Field 3. The Preference-Applied Response Header Field
The Preference-Applied response header MAY be included within a The Preference-Applied response header MAY be included within a
response message as an indication as to which Prefer tokens were response message as an indication as to which Prefer tokens were
honored by the server and applied to the processing of a request. honored by the server and applied to the processing of a request.
ABNF: ABNF:
Preference-Applied = "Preference-Applied" ":" 1#token Preference-Applied = "Preference-Applied" ":" 1#token
The syntax of the Preference-Applied header differs from that of the The syntax of the Preference-Applied header differs from that of the
Prefer header in that token values and parameters are not included. Prefer header in that token values and parameters are not included.
Use of the Preference-Applied header is only necessary when it is not Use of the Preference-Applied header is only necessary when it is not
readily and obviously apparent that a server applied a given readily and obviously apparent that a server applied a given
preference and such ambiguity might have an impact on the client's preference and such ambiguity might have an impact on the client's
handling of the response. For instance, when using either the handling of the response. For instance, when using either the
"return-representation" or "return-minimal" preferences, a client "return=representation" or "return=minimal" preferences, a client
application might not be capable of reliably determining that the application might not be capable of reliably determining if the
preference was applied simply by examining the payload of the preference was (or was not) applied simply by examining the payload
response. In such case the Preference-Applied header field can be of the response. In such case the Preference-Applied header field
used. can be used.
Request: Request:
PATCH /my-document HTTP/1.1 PATCH /my-document HTTP/1.1
Host: example.org Host: example.org
Content-Type: application/json-patch Content-Type: application/json-patch
Prefer: return-representation Prefer: return=representation
[{"op": "add", "path": "/a", "value": 1}] [{"op": "add", "path": "/a", "value": 1}]
Response: Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Preference-Applied: return-representation Preference-Applied: return=representation
Content-Location: /my-document Content-Location: /my-document
{"a": 1} {"a": 1}
4. Preference Definitions 4. Preference Definitions
The following subsections define an initial set of preferences. The following subsections define an initial set of preferences.
Additional preferences can be registered for convenience and/or to Additional preferences can be registered for convenience and/or to
promote reuse by other applications. This specification establishes promote reuse by other applications. This specification establishes
an IANA registry of such relation types (see Section 5.1). an IANA registry of such relation types (see Section 5.1).
Registered preference names MUST conform to the token rule, and MUST 4.1. The "respond-async" Preference
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.
4.1. The "return-asynch" Preference
The "return-asynch" preference indicates that the client prefers the The "respond-async" preference indicates that the client prefers the
server to respond asynchronously to a response. For instance, in 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 case when the length of time it takes to generate a response will
exceed some arbitrary threshold established by the server, the server exceed some arbitrary threshold established by the server, the server
can honor the return-asynch preference by returning a "202 Accepted" can honor the respond-async preference by returning a "202 Accepted"
response. response.
ABNF: ABNF:
return-asynch = "return-asynch" respond-async = "respond-async"
The key motivation for the "return-asynch" preference is to The key motivation for the "respond-async" preference is to
facilitate the operation of asynchronous request handling by allowing facilitate the operation of asynchronous request handling by allowing
the client to indicate to a server its capability and preference for the client to indicate to a server its capability and preference for
handling asynchronous responses. handling asynchronous responses.
An example request specifying the "return-asynch" preference: An example request specifying the "respond-async" preference:
POST /collection HTTP/1.1 POST /collection HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/plain Content-Type: text/plain
Prefer: return-asynch Prefer: respond-async
{Data} {Data}
An example asynchronous response using "202 Accepted": An example asynchronous response using "202 Accepted":
HTTP/1.1 202 Accepted HTTP/1.1 202 Accepted
Location: http://example.org/collection/123 Location: http://example.org/collection/123
While the "202 Accepted" response status is defined by While the "202 Accepted" response status is defined by
[I-D.ietf-httpbis-p2-semantics], little guidance is given on how and [I-D.ietf-httpbis-p2-semantics], little guidance is given on how and
when to use the response code and the process for determining the when to use the response code and the process for determining the
subsequent final result of the operation is left entirely undefined. subsequent final result of the operation is left entirely undefined.
Therefore, whether and how any given server supports asynchronous Therefore, whether and how any given server supports asynchronous
responses is an implementation specific detail that is considered to responses is an implementation specific detail that is considered to
be out of the scope of this specification. be out of the scope of this specification.
4.2. The "return-representation" and "return-minimal" Preferences 4.2. The "return=representation" and "return=minimal" Preferences
The "return-representation" preference indicates that the client The "return=representation" preference indicates that the client
prefers that the server include an entity representing the current prefers that the server include an entity representing the current
state of the resource in the response to a successful request. state of the resource in the response to a successful request.
The "return-minimal" preference, on the other hand, indicates that The "return=minimal" preference, on the other hand, indicates that
the client wishes the server to return only a minimal response to a the client wishes the server to return only a minimal response to a
successful request. Typically, such responses would utilize the "204 successful request. Typically, such responses would utilize the "204
No Content" status, but other codes MAY be used as appropriate, such No Content" status, but other codes MAY be used as appropriate, such
as a "200" status with a zero-length response entity. The as a "200" status with a zero-length response entity. The
determination of what constitutes an appropriate minimal response is determination of what constitutes an appropriate minimal response is
solely at the discretion of the server. solely at the discretion of the server.
ABNF: ABNF:
return-representation = "return-representation" return = "return" BWS "=" BWS ("representation" / "minimal")
return-minimal = "return-minimal"
When honoring the "return-representation" preference, the returned When honoring the "return=representation" preference, the returned
representation might not be a representation of the effective request representation might not be a representation of the effective request
URI when the request is affecting another resource. In such cases, URI when the request is affecting another resource. In such cases,
the Content-Location header can be used to identify the URI of the the Content-Location header can be used to identify the URI of the
returned representation. returned representation.
The "return-representation" preference is intended to provide a means The "return=representation" preference is intended to provide a means
of optimizing communication between the client and server by of optimizing communication between the client and server by
eliminating the need for a subsequent GET request to retrieve the eliminating the need for a subsequent GET request to retrieve the
current representation of the resource following a modification. current representation of the resource following a modification.
Currently, after successfully processing a modification request such After successfully processing a modification request such as a POST
as a POST or PUT, a server can choose to return either an entity or PUT, a server can choose to return either an entity describing the
describing the status of the operation or a representation of the status of the operation or a representation of the modified resource
modified resource itself. While the selection of which type of itself. While the selection of which type of entity to return, if
entity to return, if any at all, is solely at the discretion of the any at all, is solely at the discretion of the server, the
server, the "return-representation" preference -- along with the "return=representation" preference -- along with the "return=minimal"
"return-minimal" preference defined below -- allow the server to take preference defined below -- allow the server to take the client's
the client's preferences into consideration while constructing the preferences into consideration while constructing the response.
response.
An example request specifying the "return-representation" preference: An example request specifying the "return=representation" preference:
PATCH /item/123 HTTP/1.1 PATCH /item/123 HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/patch Content-Type: text/patch
Prefer: return-representation Prefer: return=representation
1c1 1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ < ABCDEFGHIJKLMNOPQRSTUVWXYZ
--- ---
> BCDFGHJKLMNPQRSTVWXYZ > BCDFGHJKLMNPQRSTVWXYZ
An example response containing the resource representation: An example response containing the resource representation:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Location: http://example.org/item/123 Content-Location: http://example.org/item/123
Preference-Applied: return-representation
Content-Type: text/plain Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00" ETag: "d3b07384d113edec49eaa6238ad5ff00"
BCDFGHJKLMNPQRSTVWXYZ BCDFGHJKLMNPQRSTVWXYZ
In contrast, the "return-minimal" preference can reduce the amount of In contrast, the "return=minimal" preference can reduce the amount of
data the server is required to return to the client following a data the server is required to return to the client following a
request. This can be particularly useful, for instance, when request. This can be particularly useful, for instance, when
communicating with limited-bandwidth mobile devices or when the communicating with limited-bandwidth mobile devices or when the
client simply does not require any further information about the client simply does not require any further information about the
result of a request beyond knowing if it was successfully processed. result of a request beyond knowing if it was successfully processed.
An example request specifying the "return-minimal" preference: An example request specifying the "return=minimal" preference:
POST /collection HTTP/1.1 POST /collection HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/plain Content-Type: text/plain
Prefer: return-minimal Prefer: return=minimal
{Data} {Data}
An example minimal response: An example minimal response:
HTTP/1.1 201 Created HTTP/1.1 201 Created
Location: http://example.org/collection/123 Location: http://example.org/collection/123
The "return-minimal" and "return-representation" preferences are The "return=minimal" and "return=representation" preferences are
mutually exclusive directives. A request that contains both mutually exclusive directives. It is anticipated that there will
preferences can be treated as though neither were specified. never be a situation where it will make sense for a single request to
include both preferences. Any such requests will likely be the
result of a coding error within the client. As such, a request
containing both preferences can be treated as though neither were
specified.
4.3. The "wait" Preference 4.3. The "wait" Preference
The "wait" preference can be used to establish an upper bound on the The "wait" preference can be used to establish an upper bound on the
length of time, in seconds, the client expects it will take the length of time, in seconds, the client expects it will take the
server to process the request once it has been received. In the case server to process the request once it has been received. In the case
that generating a response will take longer than the time specified, that generating a response will take longer than the time specified,
the server, or proxy, can choose to utilize an asynchronous the server, or proxy, can choose to utilize an asynchronous
processing model by returning -- for example -- a "202 Accepted" processing model by returning -- for example -- a "202 Accepted"
response. response.
skipping to change at page 12, line 12 skipping to change at page 12, line 12
Clients can abandon requests that take longer than they are prepared Clients can abandon requests that take longer than they are prepared
to wait. to wait.
For example, a server receiving the following request might choose to For example, a server receiving the following request might choose to
respond asynchronously if processing the request will take longer respond asynchronously if processing the request will take longer
than 10 seconds: than 10 seconds:
POST /collection HTTP/1.1 POST /collection HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/plain Content-Type: text/plain
Prefer: return-asynch, wait=10 Prefer: respond-async, wait=10
{Data} {Data}
4.4. The "strict" and "lenient" Processing Preferences 4.4. The "handling=strict" and "handling=lenient" Processing
Preferences
The "strict" and "lenient" preferences are mutually-exclusive The "handling=strict" and "handling=lenient" preferences indicate, at
directives indicating, at the server's discretion, how the client the server's discretion, how the client wishes the server to handle
wishes the server to handle potential error conditions that can arise potential error conditions that can arise in the processing of a
in the processing of a request. For instance, if the payload of a request. For instance, if the payload of a request contains various
request contains various minor syntactical or semantic errors, but minor syntactical or semantic errors, but the server is still capable
the server is still capable of comprehending and successfully of comprehending and successfully processing the request, a decision
processing the request, a decision must be made to either reject the must be made to either reject the request with an appropriate "4xx"
request with an appropriate "4xx" error response or go ahead with error response or go ahead with processing. The "handling=strict"
processing. The "strict" preference can be used to indicate that, preference can be used to indicate that, while any particular error
while any particular error may be recoverable, the client would may be recoverable, the client would prefer that the server reject
prefer that the server reject the request. The "lenient" preference, the request. The "handling=lenient" preference, on the other hand,
on the other hand, indicates that the client wishes the server to indicates that the client wishes the server to attempt to process the
attempt to process the request. request.
ABNF: ABNF:
handling = "strict" / "lenient" handling = "handling" BWS "=" BWS ("strict" / "lenient")
An example request specifying the "strict" preference: An example request specifying the "strict" preference:
POST /collection HTTP/1.1 POST /collection HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/plain Content-Type: text/plain
Prefer: strict Prefer: handling=strict
The "handling=strict" and "handling=lenient" preferences are mutually
exclusive directives. It is anticipated that there will never be a
situation where it will make sense for a single request to include
both preferences. Any such requests will likely be the result of a
coding error within the client. As such, a request containing both
preferences can be treated as though neither were specified.
5. IANA Considerations 5. IANA Considerations
The 'Prefer' and 'Preference-Applied' header fields should be added The 'Prefer' and 'Preference-Applied' header fields should be added
to the Permanent Message Header Fields registry defined in [RFC3864] to the Permanent Message Header Fields registry defined in [RFC3864]
(http://www.iana.org/assignments/message-headers/perm-headers.html). (http://www.iana.org/assignments/message-headers/perm-headers.html).
Header field name: Prefer Header field name: Prefer
Applicable Protocol: HTTP Applicable Protocol: HTTP
Status: Standard Status: Standard
Author: James M Snell <jasnell@gmail.com> Author: James M Snell <jasnell@gmail.com>
Change controller: IETF Change controller: IETF
Specification document: this specification Specification document: this specification, Section 2
Header field name: Preference-Applied Header field name: Preference-Applied
Applicable Protocol: HTTP Applicable Protocol: HTTP
Status: Standard Status: Standard
Author: James M Snell <jasnell@gmail.com> Author: James M Snell <jasnell@gmail.com>
Change controller: IETF Change controller: IETF
Specification document: this specification Specification document: this specification, Section 3
5.1. The Registry of Preferences 5.1. The Registry of Preferences
IANA is asked to create a new registry, "HTTP Preferences", under the IANA is asked to create a new registry, "HTTP Preferences", under the
Hypertext Transfer Protocol (HTTP) Parameters group. New Hypertext Transfer Protocol (HTTP) Parameters group. New
registrations will use the Specification Required policy [RFC5226]. registrations will use the Specification Required policy [RFC5226].
The requirements for registered preferences are described in The requirements for registered preferences are described in
Section 4. Section 4.
Registration requests consist of the completed registration template Registration requests consist of the completed registration template
skipping to change at page 13, line 38 skipping to change at page 13, line 46
Designated Expert can approve registration based on a separately Designated Expert can approve registration based on a separately
submitted template once they are satisfied that a specification will submitted template once they are satisfied that a specification will
be published. Preferences can be registered by third parties if the be published. Preferences can be registered by third parties if the
Designated Expert determines that an unregistered preference is Designated Expert determines that an unregistered preference is
widely deployed and not likely to be registered in a timely manner. widely deployed and not likely to be registered in a timely manner.
The registration template is: The registration template is:
o Preference: (A value for the Prefer request header field that o Preference: (A value for the Prefer request header field that
conforms to the syntax rule given in Section 2) conforms to the syntax rule given in Section 2)
o Value: (An enumeration or description of possible values for the
preference token).
o Optional Parameters: (An enumeration of optional parameters, and
their values, associated with the the preference token).
o Description: o Description:
o Reference: o Reference:
o Notes: [optional] o Notes: [optional]
The "Value" and "Optional Parameters" fields MAY be omitted from the
registration template if the specific preference token definition
does not define either.
Registration requests should be sent to the ietf-http-wg@w3.org Registration requests should be sent to the ietf-http-wg@w3.org
mailing list, marked clearly in the subject line (e.g., "NEW mailing list, marked clearly in the subject line (e.g., "NEW
PREFERENCE - example" to register an "example" preference). Within PREFERENCE - example" to register an "example" preference). Within
at most 14 days of the request, the Designated Expert(s) will either at most 14 days of the request, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request and, if applicable, suggestions as to how to make the request
successful. successful.
The Expert Reviewer shall ensure:
o That the requested preference name conforms to the token rule in
Section 2 and that it is not identical to any other registered
preference name;
o That any associated value, parameter names, and values conform to
the relevant ABNF grammar specifications in Section 2;
o That the name is 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.
o That requested preferences do not constrain servers, clients or
any intermediaries to any behavior required for successful
processing; and
o That the specification document defining the preference includes a
proper and complete discussion of any security considerations
relevant to the use of the preference.
5.2. Initial Registry Contents 5.2. Initial Registry Contents
The Preferences Registry's initial contents are: The Preferences Registry's initial contents are:
o Preference: return-asynch o Preference: respond-async
o Description: Indicates that the client prefers the server to o Description: Indicates that the client prefers the server to
respond asynchronously to a request. respond asynchronously to a request.
o Reference: [this specification], Section 4.1 o Reference: [this specification], Section 4.1
o Preference: return-minimal o Preference: return
o Description: Indicates that the client prefers the server return a o Value: One of either "minimal" or "representation"
minimal response to a request. o Description: When value is "minimal", indicates that the client
o Reference: [this specification], Section 4.2 prefers the server return a minimal response to a request. When
value is "representation", indicates that the client prefers the
o Preference: return-representation server to include a representation of the current state of the
o Description: Indicates that the client prefers the server to resource in response to a request.
include a representation of the current state of the resource in
response to a request.
o Reference: [this specification], Section 4.2 o Reference: [this specification], Section 4.2
o Preference: wait o Preference: wait
o Description: Indicates an upper bound to the length of time the o Description: Indicates an upper bound to the length of time the
client expects it will take the server to process the request once client expects it will take the server to process the request once
it has been received. it has been received.
o Reference: [this specification], Section 4.3 o Reference: [this specification], Section 4.3
o Preference: strict o Preference: handling
o Description: Indicates that the client wishes the server to apply o Value: One of either "strict" or "lenient"
strict validation and error handling to the processing of a o Description: When value is "strict", indicates that the client
request. wishes the server to apply strict validation and error handling to
o Reference: [this specification], Section 4.4 the processing of a request. When value is "lenient", indicates
that the client wishes the server to apply lenient validation and
o Preference: lenient error handling to the processing of the request.
o Description: Indicates that the client wishes the server to apply
lenient validation and error handling to the processing of a
request.
o Reference: [this specification], Section 4.4 o Reference: [this specification], Section 4.4
6. Security Considerations 6. Security Considerations
Specific preferences requested by a client can introduce security Specific preferences requested by a client can introduce security
considerations and concerns beyond those discussed within HTTP/1.1 considerations and concerns beyond those discussed within HTTP/1.1
[I-D.ietf-httpbis-p1-messaging] and it's additional associated [I-D.ietf-httpbis-p1-messaging] and it's additional associated
specification documents. Implementers need to refer to the specification documents. Implementers need to refer to the
specifications and descriptions of each preference to determine the specifications and descriptions of each preference to determine the
security considerations relevant to each. security considerations relevant to each.
 End of changes. 64 change blocks. 
127 lines changed or deleted 169 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/
X-Generator: pyht 0.35