| Individual Submission | J. Snell |
| Internet-Draft | October 25, 2011 |
| Intended status: Informational | |
| Expires: April 27, 2012 |
This specification defines an HTTP header that can be used by a user-agent to request that certain behaviors be implemented by a server while processing a request.¶
This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.¶
This Internet-Draft will expire on April 27, 2012.¶
Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
This specification defines a new HTTP request header that may be used by user-agents to request optional behaviors be applied by a server during the processing the request.¶
The Prefer request-header is used to indicate that particular server behaviors are preferred by the user-agent, but not required for successful completion of the request. Prefer is similar in nature to the Expect header defined by [RFC2616] with the exception that servers are allowed to ignore stated preferences.¶
Prefer = "Prefer" ":" 1#preference
preference = (return-accepted /
return-no-content /
return-content /
return-status /
wait /
priority /
handling /
detail /
preference-extension)
*prefer-params
preference-value = token / quoted-string
preference-token = token [ "=" preference-value ]
preference-extension = preference-token
prefer-params = ";" preference-token
This header is defined with an extensible syntax to allow for future values included in the Registry of Preferences (Section 12.1)). A server that does not recognize or is unable to comply with particular preference values in the Prefer header of a request MUST ignore those values and MUST NOT stop processing or signal an error.¶
An optional, arbitrary collection of "prefer-params" MAY be specified for any of the defined preference tokens as well as any preference-extensions. The meaning and application of such parameters is dependent on the definition of each preference directive and the server's implementation thereof.¶
Comparison of preference tokens is case-insensitive for unquoted tokens and is case-sensitive for quoted-string preference-extensions and prefer-params values.¶
Note that the application of a preference by the server MAY affect the caching characteristics of the response. Specifically, should the application of a preference result in a variance to the representation returned by a cacheable response, a Vary header SHOULD be included listing the Prefer header as one of the selecting header fields.¶
The Prefer request header MUST be forwarded by the proxy if the request is forwarded. In various situations, A proxy may determine that it is capable of honoring a preference independently of the server to which the request is directed. For instance, an intervening proxy may be capable of transparently providing asynchronous handling of a request using a 202 Accepted responses independently of the origin server. Such proxies could choose to honor the "return-accepted" preference. Individual preference directives MAY define their own requirements and restrictions as to whether and how proxies may apply the preference to a request independently of the origin server.¶
The "return-accepted" preference indicates that the user-agent prefers the server to respond with a 202 Accepted status in the case where the length of time it takes to generate a response will exceed some arbitrary threshold established by the server.¶
return-accepted = "return-accepted"
The key motivation for the "return-accepted" preference is to facilitate the operation of asynchronous request handling by allowing the user-agent to indicate to a server it's capability and preference for handling 202 Accepted responses.¶
The "return-content" preference indicates that the user-agent prefers that the server include an entity representing the current state of the resource in the response to a successful request.¶
return-content = "return-content"
When honoring the "return-content" preference, the server MUST include a Content-Location header specifying the URI of the resource representation being returned. Per section 6.1 of [TODO:draft-ietf-httpbis-p2-semantics], the presence of the Content-Location header in the response asserts that the payload is a representation of the resource identified by the Content-Location URI.¶
The "return-content" preference is intended primarily to provide a means of optimizing communication between the user-agent and server by eliminating the need for a subsequent GET request to retrieve the current representation of the resource following a modification.¶
Currently, after successfully processing a modification request such as a POST or PUT, a server may choose to return either an entity describing the status of the operation or a representation of the modified resource itself. While the selection of which type of entity to return, if any at all, is solely at the discretion of the server, the "return-content" preference -- along with the "return-status" and "return-no-content" directives defined below -- allow the server to take the user-agent's preferences into consideration while constructing the response.¶
The "return-status" preference indicates that the user-agent prefers the server to include an entity describing the status of the request in the response as opposed to returning a representation of the current state of the resource.¶
return-status = "return-status"
When honoring the "return-status" preference, the server SHOULD NOT include a Content-Location header in the response.¶
The "return-no-content" preference indicates that the user-agent wishes the server to not include an entity in the response to a successful request. Typically, such responses would use the 204 No Content status, but other codes MAY be used as appropriate. Regardless of the status returned, when honoring the "return-no-content" preference, the server MUST NOT include an entity within the response.¶
return-no-content = "return-no-content"
The "return-no-content" preference is intended to provide a means of optimizing communication between the user-agent and server by reducing the amount of data the server is required to return to the user-agent following a modification request. This can be particularly useful, for instance, when communicating with limited-bandwidth mobile devices or when the user-agent simply does not require any further information about the result of a request beyond knowing if it was successfully processed.¶
The "wait" preference can be used to establish an upper bound on the length of time, in seconds, the user-agent is willing to wait for a response, after which the user-agent may choose to abandon the request. In the case generating a response will take longer than the time specified, the server, or proxy, can choose to either return a 202 Accepted response, cancel processing, or continue attempting to complete the request.¶
wait = "wait" "=" delta-seconds
ED NOTE: This preference directive is currently exploratory in nature. I've added it to solicit feedback as to it's general utility. It is possible that I may pull this back out.¶
The "priority" preference can be used to indicate the priority a user-agent wishes the server or proxy to assign to processing the request relative to other requests that may be concurrently received. The application and assignment of a priority value to requests is entirely at the discretion of the server or proxy. Priority values are specified as non-negative integers within the range 0-100, inclusive, where the value 0 indicates that the user-agent wishes to have a server-determined default priority assigned to the request, and all other values indicate a strictly decreasing priority as the integer value increases.¶
priority = "priority" "=" "100" / (1*2DIGIT)
Implementations are free to apply additional constraints on the range of acceptable values for this directive but MUST NOT signal an error or fail to process the request should the user-agent provide a value outside the acceptable range. In such cases, the server SHOULD either ignore the preference or apply a reasonable default value.¶
ED NOTE: This preference directive is currently exploratory in nature. I've added it to solicit feedback as to it's general utility. It is possible that I may pull this back out.¶
The "strict" and "lenient" preferences are mutually-exclusive directives indicating, at the servers discretion, how the user-agent wishes the server to handle potential error conditions that may arise in the processing of a request. For instance, if the payload of a request contains various minor syntactical or semantic errors, but the server is still capable of comprehending and successfully processing the request, a decision must be made to either reject the request with an appropriate 4xx error response or to go ahead with processing. The "strict" preference can be used by the user-agent to indicate that, in such conditions, it would prefer that the server reject the request, while the "lenient" preference indicates that the user-agent would prefer the server to attempt to process the request. The specific meaning and application of the "strict" and "lenient" directives is specific to each type of resource, the request method and the operation of the server.¶
handling = "strict" / "lenient"
ED NOTE: This preference directive is currently exploratory in nature. I've added it to solicit feedback as to it's general utility. It is possible that I may pull this back out.¶
The "detail" preference specifies, at the servers discretion, the level of detail the user-agent wishes the server to provide within a response to an operation. This preference is akin to specifying the level of verbose output an operation should generate or to specifying the trace level within a debug log. The detail level is specified as a non-negative integer in the range 0-100, where the value 0 indicates a server-determined default detail level and all other values specify a strictly decreasing level of detail as the integer value increases.¶
detail = "detail" "=" "100" / (1*2DIGIT)
Implementations are free to apply additional constraints on the range of acceptable values for this directive but MUST NOT signal an error or fail to process the request should the user-agent provide a value outside the acceptable range. In such cases, the server SHOULD either ignore the preference or apply a reasonable default value.¶
One example of a potential use for the application of the "detail" preference would be in deciding the amount of detailed error information a server includes in the payload of a 4xx or 5xx response. Solely at the discretion of the server, an error response to a request specifying a higher detail level (e.g., detail=1) may included significantly more detailed information about the error condition than an error response specifying a much lower detail level (e.g., detail=10).¶
Well-defined 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 Section 12.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 are available for less specific use.¶
Registered preferences MUST NOT constrain servers, user-agents 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.¶
Header field name: Prefer
Applicable Protocol: HTTP
Status:
Author/Change controller: IETF
Specification document: this specification
Preferences are registered on the advice of a Designated Expert (appointed by the IESG or their delegate), with a Specification Required (using terminology from [RFC5226]).¶
The requirements for registered preferences are described in Section 11¶
Registration requests consist of the completed registration template below, typically published in an RFC or Open Standard (in the sense described by [RFC2026], Section 7). However, to allow for the allocation of values prior to publication, the Designated Expert may approve registration once they are satisfied that a specification will be published.¶
Note that relation types can be registered by third parties, if the Designated Expert determines that an unregistered relation type is widely deployed and not likely to be registered in a timely manner.¶
The registration template is:¶
Registration requests should be sent to the preferences@ietf.org mailing list, marked clearly in the subject line (e.g., "NEW PREFERENCE - example" to register an "example" preference).¶
Within at most 14 days of the request, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful.¶
Decisions (or lack thereof) made by the Designated Expert can be first appealed to Application Area Directors (contactable using app-ads@tools.ietf.org email address or directly by looking up their email addresses on http://www.iesg.org/ website) and, if the appellant is not satisfied with the response, to the full IESG (using the iesg@iesg.org mailing list).¶
IANA should only accept registry updates from the Designated Expert(s), and should direct all requests for registration to the review mailing list.¶
The Preferences Registry's initial contents are:¶