< draft-snell-http-prefer-14.txt   draft-snell-http-prefer-15.txt >
Network Working Group J. Snell Network Working Group J. Snell
Internet-Draft August 23, 2012 Internet-Draft October 12, 2012
Intended status: Standards Track Intended status: Standards Track
Expires: February 24, 2013 Expires: April 15, 2013
Prefer Header for HTTP Prefer Header for HTTP
draft-snell-http-prefer-14 draft-snell-http-prefer-15
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 implemented 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
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 February 24, 2013. This Internet-Draft will expire on April 15, 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 10 skipping to change at page 2, line 10
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
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. Content Negotiation and Cache Considerations . . . . . . . 6 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. The Preference-Applied Response Header Field . . . . . . . . . 7
3. Preference Definitions . . . . . . . . . . . . . . . . . . . . 7 4. Preference Definitions . . . . . . . . . . . . . . . . . . . . 8
3.1. The "return-asynch" Preference . . . . . . . . . . . . . . 7 4.1. The "return-asynch" Preference . . . . . . . . . . . . . . 8
3.2. The "return-representation" Preference . . . . . . . . . . 8 4.2. The "return-representation" and "return-minimal"
3.3. The "return-minimal" Preference . . . . . . . . . . . . . 9 Preferences . . . . . . . . . . . . . . . . . . . . . . . 9
3.4. The "wait" Preference . . . . . . . . . . . . . . . . . . 10 4.3. The "wait" Preference . . . . . . . . . . . . . . . . . . 11
3.5. The "strict" and "lenient" Processing Preferences . . . . 11 4.4. The "strict" and "lenient" Processing Preferences . . . . 12
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
4.1. The Registry of Preferences . . . . . . . . . . . . . . . 12 5.1. The Registry of Preferences . . . . . . . . . . . . . . . 13
4.2. Initial Registry Contents . . . . . . . . . . . . . . . . 13 5.2. Initial Registry Contents . . . . . . . . . . . . . . . . 14
5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14
6. Normative References . . . . . . . . . . . . . . . . . . . . . 14 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1. Normative References . . . . . . . . . . . . . . . . . . . 15
7.2. Informative References . . . . . . . . . . . . . . . . . . 15
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 is 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 --
similar to that defined for the Atom Publishing Protocol [RFC 5023] similar to that defined for the Atom Publishing Protocol [RFC5023] --
-- the server is given the option of returning either a complete the server is given the option of returning either a complete
representation of a modified resource or a minimal response that representation of a modified resource or a minimal response that
indicates only the successful completion of the operation. The indicates only the successful completion of the operation. The
selection of which type of response to return to the client generally selection of which type of response to return to the client generally
has no bearing on the successful processing of the request but could, has no bearing on the successful processing of the request but could,
for instance, have an impact on what actions the client must take for instance, have an impact on what actions the client must take
after receiving the response. That is, returning a representation of after receiving the response. That is, returning a representation of
the modified resource within the response can allow the client to the modified resource within the response can allow the client to
avoid sending an additional subsequent GET request. avoid sending an additional subsequent GET request.
Similarly, servers that process requests are often faced with Similarly, servers that process requests are often faced with
skipping to change at page 4, line 30 skipping to change at page 4, line 30
In this document, the key words "MUST", "MUST NOT", "REQUIRED", In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in [RFC2119]. and "OPTIONAL" are to be interpreted as described in [RFC2119].
1.1. Syntax Notation 1.1. Syntax Notation
This specification uses the Augmented Backus-Naur Form (ABNF) This specification uses the Augmented Backus-Naur Form (ABNF)
notation of [RFC5234] and includes, by reference, the "token", notation of [RFC5234] and includes, by reference, the "token",
"word", "OWS", "BWS" rules and the #rule extension as defined within "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]. Sections 3.2.1 and 3.2.4 of [I-D.ietf-httpbis-p1-messaging].
2. The Prefer Request Header Field 2. The Prefer Request Header Field
The Prefer request-header field is used to indicate that particular The Prefer request header field is used to indicate that particular
server behaviors are preferred by the client, but not required for server behaviors are preferred by the client, but not required for
successful completion of the request. Prefer is similar in nature to successful completion of the request. Prefer is similar in nature to
the Expect header field defined by Section 9.3 of the Expect header field defined by Section 6.1.2 of
[I-D.ietf-httpbis-p2-semantics] with the exception that servers are [I-D.ietf-httpbis-p2-semantics] with the exception that servers are
allowed to ignore stated preferences. allowed to ignore stated preferences.
ABNF:
Prefer = "Prefer" ":" 1#preference Prefer = "Prefer" ":" 1#preference
preference = token [ BWS "=" BWS word ] preference = token [ BWS "=" BWS word ]
*( OWS ";" [ OWS parameter ] ) *( OWS ";" [ OWS parameter ] )
parameter = token [ BWS "=" BWS word ] parameter = token [ BWS "=" BWS word ]
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 4.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 MUST NOT stop processing or signal an MUST ignore those tokens and continue processing instead of
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:
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.
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.
Comparison of preference token names is case-insensitive while values Comparison of preference token names is case-insensitive while values
are case-sensitive regardless of whether token or quoted-string are case-sensitive regardless of whether token or quoted-string
values are used. values are used.
The Prefer request header field is end-to-end and MUST be forwarded The Prefer header field is end-to-end and SHOULD be forwarded by a
by a proxy if the request is forwarded. proxy if the request is forwarded unless Prefer is explicitly
identified as being hop-by-hop using the Connection header field
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 "return-asynch" preference on their own
despite whether the origin is capable or willing to do so. In such despite whether the origin is capable or willing to do so.
cases, however, the proxy is still required to forward the Prefer
header on to the origin server.
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.
As per Section 3.2 of [I-D.ietf-httpbis-p1-messaging],
Implementations MUST support multiple instances of the Prefer header Implementations MUST support multiple instances of the Prefer header
field in a single message, as well as multiple preference tokens field in a single message, as well as multiple preference tokens
separated by commas in a single Prefer header field. The following separated by commas in a single Prefer header field. The following
examples are equivalent: examples are equivalent:
Multiple Prefer Header Fields: Multiple Prefer Header Fields:
POST /foo HTTP/1.1 POST /foo HTTP/1.1
Host: example.org Host: example.org
Prefer: return-asynch Prefer: return-asynch
Prefer: wait=100 Prefer: wait=100
Date: Tue, 20 Dec 2011 12:34:56 GMT Date: Tue, 20 Dec 2011 12:34:56 GMT
Single Prefer Header Field: Single Prefer Header Field:
POST /foo HTTP/1.1 POST /foo HTTP/1.1
Host: example.org Host: example.org
Prefer: wait=100, return-asynch Prefer: wait=100, return-asynch
Date: Tue, 20 Dec 2011 12:34:56 GMT Date: Tue, 20 Dec 2011 12:34:56 GMT
No significance is given to the order in which preference tokens To avoid possible ambiguity, individual preference tokens SHOULD NOT
appear within a request. appear multiple times within a single request. If any preference is
specified more than once, only the first instance is to be
2.1. Content Negotiation and Cache Considerations considered. All subsequent occurrences SHOULD be ignored without
signaling an error or otherwise altering the processing of the
request. This is the only case in which the ordering of preferences
within a request is considered to be significant.
Note that while the Prefer header field is not intended to be used as Due to the inherent complexities involved with properly implementing
content negotiation mechanism, the application of a preference server-driven content negotiation, effective caching, and the
potentially could affect the caching characteristics of a response. application of optional preferences, implementors are urged to
Specifically, if a server supports the optional application of a exercise caution when using preferences in a way that impacts the
preference that could even just potentially result in a variance to a caching of a response and SHOULD NOT use the Prefer header mechanism
for content negotiation. If a server supports the optional
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 with 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.
Because of the inherent complexities involved with properly 2.1. Examples
implementing server-driven content negotiation, effective caching,
and the application of optional preferences, implementors must
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 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 response cannot be processed within 10 seconds. An undefined
"priority" preference is also specified: "priority" preference is also specified:
Prefer: return-asynch, wait=10; Prefer: return-asynch, wait=10;
Prefer: priority=5; Prefer: priority=5;
2. Use lenient processing: 2. Use lenient processing:
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 requesting a response status code of "204" for a preference:
successful response:
Prefer: return-minimal; status=204 Prefer: return-minimal; foo="some parameter"
3. Preference Definitions 3. The Preference-Applied Response Header Field
The Preference-Applied response header MAY be included within a
response message as an indication as to which Prefer tokens were
honored by the server and applied to the processing of a request.
ABNF:
Preference-Applied = "Preference-Applied" ":" 1#token
The syntax of the Preference-Applied header differs from that of the
Prefer header in that token values and parameters are not included.
Use of the Preference-Applied header is only necessary when it is not
readily and obviously apparent that a server applied a given
preference and such ambiguity might have an impact on the client's
handling of the response. For instance, when using either the
"return-representation" or "return-minimal" preferences, a client
application might not be capable of reliably determining that the
preference was applied simply by examining the payload of the
response. In such case the Preference-Applied header field can be
used.
Request:
PATCH /my-document HTTP/1.1
Host: example.org
Content-Type: application/json-patch
Prefer: return-representation
[{"op": "add", "path": "/a", "value": 1}]
Response:
HTTP/1.1 200 OK
Content-Type: application/json
Preference-Applied: return-representation
Content-Location: /my-document
{"a": 1}
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 4.1). an IANA registry of such relation types (see Section 5.1).
Registered preference names MUST conform to the token rule, and MUST Registered preference names MUST conform to the token rule, and MUST
be compared character-by-character in a case-insensitive fashion. be compared character-by-character in a case-insensitive fashion.
They SHOULD be appropriate to the specificity of the preference; They SHOULD be appropriate to the specificity of the preference;
i.e., if the semantics are highly specific to a particular i.e., if the semantics are highly specific to a particular
application, the name should reflect that, so that more general names application, the name should reflect that, so that more general names
remain available for less specific use. remain available for less specific use.
Registered preferences MUST NOT constrain servers, clients or any Registered preferences MUST NOT constrain servers, clients or any
intermediaries involved in the exchange and processing of a request intermediaries involved in the exchange and processing of a request
to any behavior required for successful processing. The use and to any behavior required for successful processing. The use and
application of a preference within a given request MUST be optional application of a preference within a given request MUST be optional
on the part of all participants. on the part of all participants.
3.1. The "return-asynch" Preference 4.1. The "return-asynch" Preference
The "return-asynch" preference indicates that the client prefers the The "return-asynch" 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 either a "202 can honor the return-asynch preference by returning a "202 Accepted"
Accepted" or "303 See Other" response. response.
ABNF: ABNF:
return-asynch = "return-asynch" return-asynch = "return-asynch"
The key motivation for the "return-asynch" preference is to The key motivation for the "return-asynch" 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.
skipping to change at page 8, line 19 skipping to change at page 9, line 19
Content-Type: text/plain Content-Type: text/plain
Prefer: return-asynch Prefer: return-asynch
{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
An alternative asynchronous response using "303 See Other": While the "202 Accepted" response status is defined by
[I-D.ietf-httpbis-p2-semantics], little guidance is given on how and
HTTP/1.1 303 See Other when to use the response code and the process for determining the
Location: http://example.org/collection/123 subsequent final result of the operation is left entirely undefined.
Retry-After: 10 Therefore, whether and how any given server supports asynchronous
responses is an implementation specific detail that is considered to
be out of the scope of this specification.
3.2. The "return-representation" Preference 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 client wishes the server to return only a minimal response to a
successful request. Typically, such responses would utilize the "204
No Content" status, but other codes MAY be used as appropriate, such
as a "200" status with a zero-length response entity. The
determination of what constitutes an appropriate minimal response is
solely at the discretion of the server.
ABNF: ABNF:
return-representation = "return-representation" return-representation = "return-representation"
return-minimal = "return-minimal"
When honoring the "return-representation" preference, the server MUST When honoring the "return-representation" preference, the returned
include a Content-Location header field specifying the URI of the representation might not be a representation of the effective request
resource representation being returned. Per section 6.1 of URI when the request is affecting another resource. In such cases,
[I-D.ietf-httpbis-p2-semantics], the presence of the Content-Location the Content-Location header can be used to identify the URI of the
header field in the response asserts that the payload is a returned representation.
representation of the resource identified by the Content-Location
URI.
The "return-representation" preference is intended primarily to The "return-representation" preference is intended to provide a means
provide a means of optimizing communication between the client and of optimizing communication between the client and server by
server by eliminating the need for a subsequent GET request to eliminating the need for a subsequent GET request to retrieve the
retrieve the current representation of the resource following a current representation of the resource following a modification.
modification.
Currently, after successfully processing a modification request such Currently, after successfully processing a modification request such
as a POST or PUT, a server can choose to return either an entity as a POST or PUT, a server can choose to return either an entity
describing the status of the operation or a representation of the describing the status of the operation or a representation of the
modified resource itself. While the selection of which type of modified resource itself. While the selection of which type of
entity to return, if any at all, is solely at the discretion of the entity to return, if any at all, is solely at the discretion of the
server, the "return-representation" preference -- along with the server, the "return-representation" preference -- along with the
"return-minimal" preference defined below -- allow the server to take "return-minimal" preference defined below -- allow the server to take
the client's preferences into consideration while constructing the the client's preferences into consideration while constructing the
response. response.
An example request specifying the "return-representation" preference: An example request specifying the "return-representation" preference:
PUT /collection/123 HTTP/1.1 PATCH /item/123 HTTP/1.1
Host: example.org Host: example.org
Content-Type: text/plain Content-Type: text/patch
Prefer: return-representation Prefer: return-representation
{Data} 1c1
< ABCDEFGHIJKLMNOPQRSTUVWXYZ
---
> 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/collection/123 Content-Location: http://example.org/item/123
Preference-Applied: return-representation
Content-Type: text/plain Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00" ETag: "d3b07384d113edec49eaa6238ad5ff00"
{Data} BCDFGHJKLMNPQRSTVWXYZ
The "return-minimal" and "return-representation" preferences are
mutually exclusive directives that MUST NOT be used in combination
within a single request. If a server receives a request containing
both the "return-minimal" and "return-representation" preferences, it
MAY choose to ignore either or both of the stated preferences but
MUST NOT signal an error or fail to process the request solely on the
basis of those preferences.
3.3. The "return-minimal" Preference
The "return-minimal" preference indicates that the client wishes the
server to return a minimal response to a successful request.
Typically, such responses would utilize the "204 No Content" status,
but other codes MAY be used as appropriate, such as a "200" status
with a zero-length response entity. The determination of what
constitutes an appropriate minimal response is solely at the
discretion of the server.
ABNF:
return-minimal = "return-minimal"
The "return-minimal" preference is intended to provide a means of In contrast, the "return-minimal" preference can reduce the amount of
optimizing communication between the client and server by reducing data the server is required to return to the client following a
the amount of data the server is required to return to the client request. This can be particularly useful, for instance, when
following a request. This can be particularly useful, for instance, communicating with limited-bandwidth mobile devices or when the
when 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
Content-Length: 0
The "return-minimal" and "return-representation" preferences are The "return-minimal" and "return-representation" preferences are
mutually exclusive directives that MUST NOT be used in combination mutually exclusive directives. A request that contains both
within a single request. If a server receives a request containing preferences can be treated as though neither were specified.
both the "return-minimal" and "return-representation" preferences, it
MAY choose to ignore either or both of the stated preferences but
MUST NOT signal an error or fail to process the request solely on the
basis of those preferences.
3.4. 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 is willing to wait for a length of time, in seconds, the client expects it will take the
response, after which the client might choose to abandon the request. server to process the request once it has been received. In the case
In the case generating a response will take longer than the time that generating a response will take longer than the time specified,
specified, the server, or proxy, MAY choose to utilize an the server, or proxy, can choose to utilize an asynchronous
asynchronous processing model by returning, for example, "202 processing model by returning -- for example -- a "202 Accepted"
Accepted" or "303 See Other" responses. response.
ABNF: ABNF:
wait = "wait" BWS "=" BWS delta-seconds wait = "wait" BWS "=" BWS delta-seconds
Clients specifying the "wait" preference SHOULD also use the Date It is important to consider that HTTP messages spend some time
header field, as specified in Section 9.2 of traversing the network and being processed by intermediaries. This
[I-D.ietf-httpbis-p2-semantics], within the request to establish the increases the length of time that a client will wait for a response
time at which the client began waiting for the completion of the in addition to the time the server takes to process the request. A
request. Failing to include a Date header field in the request would client that has strict timing requirements can estimate these factors
require the server to use the instant it received or began processing and adjust the wait value accordingly.
the request as the baseline for determining how long the client has
been waiting which could yield unintended results.
The lack of a Date header in the request, or poor clock As with other preferences, the "wait" preference could be ignored.
synchronization between the client and server makes it impossible to Clients can abandon requests that take longer than they are prepared
determine the exact length of time the client has already been to wait.
waiting when the request is received by the server. The only
reliable information conveyed by the wait preference is that the
client is not expecting the server to spend more than the specified
time on request processing and can terminate the transaction at any
time.
An example request specifying the "wait" and "return-asynch" For example, a server receiving the following request might choose to
preferences to indicate that the client wishes the server to respond respond asynchronously if processing the request will take longer
asynchronously if processing of the request will take longer than 10 than 10 seconds:
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: return-asynch, wait=10
Date: Tue, 20 Dec 2011 12:34:56 GMT
{Data} {Data}
3.5. The "strict" and "lenient" Processing Preferences 4.4. The "strict" and "lenient" Processing Preferences
The "strict" and "lenient" preferences are mutually-exclusive The "strict" and "lenient" preferences are mutually-exclusive
directives indicating, at the server's discretion, how the client directives indicating, at the server's discretion, how the client
wishes the server to handle potential error conditions that can arise wishes the server to handle potential error conditions that can arise
in the processing of a request. For instance, if the payload of a in the processing of a request. For instance, if the payload of a
request contains various minor syntactical or semantic errors, but request contains various minor syntactical or semantic errors, but
the server is still capable of comprehending and successfully the server is still capable of comprehending and successfully
processing the request, a decision must be made to either reject the processing the request, a decision must be made to either reject the
request with an appropriate "4xx" error response or go ahead with request with an appropriate "4xx" error response or go ahead with
processing. The "strict" preference can be used by the client to processing. The "strict" preference can be used to indicate that,
indicate that, in such conditions, it would prefer that the server while any particular error may be recoverable, the client would
reject the request, while the "lenient" preference indicates that the prefer that the server reject the request. The "lenient" preference,
client would prefer the server to attempt to process the request. on the other hand, indicates that the client wishes the server to
The specific meaning and application of the "strict" and "lenient" attempt to process the request.
directives is specific to each type of resource, the request method
and the operation of the server.
ABNF: ABNF:
handling = "strict" / "lenient" handling = "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: strict
An example request specifying the "lenient" preference: 5. IANA Considerations
POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: lenient
4. IANA Considerations
The 'Prefer' header field should be added to the Permanent Message The 'Prefer' and 'Preference-Applied' header fields should be added
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: 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
4.1. The Registry of Preferences Header field name: Preference-Applied
Applicable Protocol: HTTP
Status: Standard
Author: James M Snell <jasnell@gmail.com>
Change controller: IETF
Specification document: this specification
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 3. Section 4.
Registration requests consist of the completed registration template Registration requests consist of the completed registration template
below, typically published in an RFC or Open Standard (in the sense below, typically published in the required specification. However,
described by Section 7 of [RFC2026]). However, to allow for the to allow for the allocation of values prior to publication, the
allocation of values prior to publication, the Designated Expert can Designated Expert can approve registration based on a separately
approve registration once they are satisfied that a specification submitted template once they are satisfied that a specification will
will be published. be published. Preferences can be registered by third parties if the
Note that 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 Description: o Description:
o Reference: o Reference:
o Notes: [optional] o Notes: [optional]
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). PREFERENCE - example" to register an "example" preference). Within
at most 14 days of the request, the Designated Expert(s) will either
Within at most 14 days of the request, the Designated Expert(s) will approve or deny the registration request, communicating this decision
either approve or deny the registration request, communicating this to the review list and IANA. Denials should include an explanation
decision to the review list and IANA. Denials should include an and, if applicable, suggestions as to how to make the request
explanation and, if applicable, suggestions as to how to make the successful.
request successful.
4.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: return-asynch
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 3.1 o Reference: [this specification], Section 4.1
o Preference: return-minimal o Preference: return-minimal
o Description: Indicates that the client prefers the server return a o Description: Indicates that the client prefers the server return a
minimal response to a request. minimal response to a request.
o Reference: [this specification], Section 3.3 o Reference: [this specification], Section 4.2
o Preference: return-representation o Preference: return-representation
o Description: Indicates that the client prefers the server to o Description: Indicates that the client prefers the server to
include a representation of the current state of the resource in include a representation of the current state of the resource in
response to a request. response to a request.
o Reference: [this specification], Section 3.2 o Reference: [this specification], Section 4.2
o Preference: wait o Preference: wait
o Description: Indicates an upper bound to the lenght of time the o Description: Indicates an upper bound to the length of time the
client is willing to wait for a response, after which the request client expects it will take the server to process the request once
can be aborted. it has been received.
o Reference: [this specification], Section 3.4 o Reference: [this specification], Section 4.3
o Preference: strict o Preference: strict
o Description: Indicates that the client wishes the server to apply o Description: Indicates that the client wishes the server to apply
strict validation and error handling to the processing of a strict validation and error handling to the processing of a
request. request.
o Reference: [this specification], Section 4.4
o Reference: [this specification], Section 3.5
o Preference: lenient o Preference: lenient
o Description: Indicates that the client wishes the server to apply o Description: Indicates that the client wishes the server to apply
lenient validation and error handling to the processing of a lenient validation and error handling to the processing of a
request. request.
o Reference: [this specification], Section 3.5 o Reference: [this specification], Section 4.4
5. 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 in HTTP/1.1 Parts considerations and concerns beyond those discussed within HTTP/1.1
1 [I-D.ietf-httpbis-p1-messaging], 2 [I-D.ietf-httpbis-p2-semantics], [I-D.ietf-httpbis-p1-messaging] and it's additional associated
3 [I-D.ietf-httpbis-p3-payload], 4 [I-D.ietf-httpbis-p4-conditional], specification documents. Implementers need to refer to the
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 specifications and descriptions of each preference to determine the
security considerations relevant to each. security considerations relevant to each.
A server could incur greater costs in attempting to comply with a A server could incur greater costs in attempting to comply with a
particular preference (for instance, the cost of providing a particular preference (for instance, the cost of providing a
representation in a response that would not ordinarily contain one; representation in a response that would not ordinarily contain one;
or the commitment of resources necessary to track state for an or the commitment of resources necessary to track state for an
asynchronous response). Unconditional compliance from a server could asynchronous response). Unconditional compliance from a server could
allow the use of preferences for denial of service. A server can allow the use of preferences for denial of service. A server can
ignore an expressed preference to avoid expending resources that it ignore an expressed preference to avoid expending resources that it
does not wish to commit. does not wish to commit.
6. Normative References 7. References
7.1. Normative References
[I-D.ietf-httpbis-p1-messaging] [I-D.ietf-httpbis-p1-messaging]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and (HTTP/1.1): Message Syntax and Routing",
J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and draft-ietf-httpbis-p1-messaging-21 (work in progress),
Message Parsing", draft-ietf-httpbis-p1-messaging-18 (work October 2012.
in progress), January 2012.
[I-D.ietf-httpbis-p2-semantics] [I-D.ietf-httpbis-p2-semantics]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and (HTTP/1.1): Semantics and Content",
J. Reschke, "HTTP/1.1, part 2: Message Semantics", draft-ietf-httpbis-p2-semantics-21 (work in progress),
draft-ietf-httpbis-p2-semantics-18 (work in progress), October 2012.
January 2012.
[I-D.ietf-httpbis-p3-payload]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and
J. Reschke, "HTTP/1.1, part 3: Message Payload and Content
Negotiation", draft-ietf-httpbis-p3-payload-18 (work in
progress), January 2012.
[I-D.ietf-httpbis-p4-conditional]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and
J. Reschke, "HTTP/1.1, part 4: Conditional Requests",
draft-ietf-httpbis-p4-conditional-18 (work in progress),
January 2012.
[I-D.ietf-httpbis-p5-range]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and
J. Reschke, "HTTP/1.1, part 5: Range Requests and Partial
Responses", draft-ietf-httpbis-p5-range-18 (work in
progress), January 2012.
[I-D.ietf-httpbis-p6-cache]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y.,
Nottingham, M., and J. Reschke, "HTTP/1.1, part 6:
Caching", draft-ietf-httpbis-p6-cache-18 (work in
progress), January 2012.
[I-D.ietf-httpbis-p7-auth]
Fielding, R., Gettys, J., Mogul, J., Nielsen, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and
J. Reschke, "HTTP/1.1, part 7: Authentication",
draft-ietf-httpbis-p7-auth-18 (work in progress),
January 2012.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, October 1996. 3", BCP 9, RFC 2026, October 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864, Procedures for Message Header Fields", BCP 90, RFC 3864,
September 2004. September 2004.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
7.2. Informative References
[RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing
Protocol", RFC 5023, October 2007.
Author's Address Author's Address
James M Snell James M Snell
Email: jasnell@gmail.com Email: jasnell@gmail.com
 End of changes. 70 change blocks. 
246 lines changed or deleted 219 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