One document matched: draft-snell-http-prefer-04.xml
<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2616 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml'>
<!ENTITY rfc4918 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4918.xml'>
<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3864 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3864.xml'>
<!ENTITY rfc2434 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2434.xml'>
<!ENTITY rfc5226 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml'>
<!ENTITY rfc2026 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2026.xml'>
]>
<?rfc toc="yes"?>
<?rfc strict="yes"?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<rfc category="info" ipr="trust200811" docName="draft-snell-http-prefer-04">
<front>
<title abbrev="HTTP Prefer">
Prefer Header for HTTP
</title>
<author initials="J.M." surname="Snell" fullname="James M Snell">
<organization></organization>
<address>
<postal>
<street></street>
<city></city> <region></region> <code></code>
<country></country>
</postal>
<phone></phone>
<email>jasnell@gmail.com</email>
<uri></uri>
</address>
</author>
<date month="October" year="2011" />
<area>Applications</area>
<workgroup>Individual Submission</workgroup>
<keyword>I-D</keyword>
<keyword>http</keyword>
<keyword>prefer</keyword>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>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.</t>
<t>In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
are to be interpreted as described in <xref target="RFC2119" />.</t>
</section>
<section title="The Prefer Request Header" anchor="prefer">
<t>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 <xref target="RFC2616" /> with the exception
that servers are allowed to ignore stated preferences.</t>
<figure><artwork>
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
</artwork></figure>
<t>This header is defined with an extensible syntax to allow for future
values included in the <xref target="registry">Registry of Preferences</xref>).
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.</t>
<t>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.</t>
<t>Comparison of preference tokens is case-insensitive for unquoted
tokens and is case-sensitive for quoted-string preference-extensions and
prefer-params values.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="The "return-accepted" Preference" anchor="return-accepted">
<t>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.</t>
<figure><artwork>
return-accepted = "return-accepted"
</artwork></figure>
<t>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.</t>
</section>
<section title="The "return-content" Preference" anchor="return-content">
<t>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.</t>
<figure><artwork>
return-content = "return-content"
</artwork></figure>
<t>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.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="The "return-status" Preference" anchor="return-status">
<t>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.</t>
<figure><artwork>
return-status = "return-status"
</artwork></figure>
<t>When honoring the "return-status" preference, the server
SHOULD NOT include a Content-Location header in the response.</t>
</section>
<section title="The "return-no-content" Preference" anchor="return-no-content">
<t>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.</t>
<figure><artwork>
return-no-content = "return-no-content"
</artwork></figure>
<t>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.</t>
</section>
<section title="The "wait" Preference" anchor="wait">
<t>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.</t>
<figure><artwork>
wait = "wait" "=" delta-seconds
</artwork></figure>
</section>
<section title="The "priority" Preference" anchor="priority">
<t>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.</t>
<t>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.</t>
<figure><artwork>
priority = "priority" "=" "100" / (1*2DIGIT)
</artwork></figure>
<t>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.</t>
</section>
<section title="The "strict" and "lenient" Processing Preferences" anchor="handling">
<t>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.</t>
<t>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.</t>
<figure><artwork>
handling = "strict" / "lenient"
</artwork></figure>
</section>
<section title="The "detail" Preference" anchor="detail">
<t>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.</t>
<t>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.</t>
<figure><artwork>
detail = "detail" "=" "100" / (1*2DIGIT)
</artwork></figure>
<t>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.</t>
<t>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).</t>
</section>
<section title="Registered Preferences" anchor="requirements">
<t>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
<xref target="registry" />.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="IANA Considerations">
<t>The 'Prefer' header should be added to
the permanent registry (see <xref target="RFC3864" />).</t>
<t><figure><artwork>
Header field name: Prefer
Applicable Protocol: HTTP
Status:
Author/Change controller: IETF
Specification document: this specification
</artwork></figure></t>
<section title="The Registry of Preferences" anchor="registry">
<t>Preferences are registered on the advice of a Designated Expert
(appointed by the IESG or their delegate), with a Specification
Required (using terminology from <xref target="RFC5226" />).</t>
<t>The requirements for registered preferences are described in
<xref target="requirements" /></t>
<t>Registration requests consist of the completed registration template
below, typically published in an RFC or Open Standard (in the sense
described by <xref target="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.</t>
<t>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.</t>
<t>The registration template is:</t>
<t>
<list style="symbols">
<t>Preference: (A value for the Prefer request header that conforms to the
syntax rule given in <xref target="prefer"/>)</t>
<t>Description:</t>
<t>Reference:</t>
<t>Notes: [optional]</t>
<t>Application Data: [optional]</t>
</list>
</t>
<t>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).</t>
<t>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.</t>
<t>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).</t>
<t>IANA should only accept registry updates from the Designated
Expert(s), and should direct all requests for registration to the
review mailing list.</t>
<section title="Initial Registry Contents">
<t>The Preferences Registry's initial contents are:</t>
<t>
<list style="symbols">
<t>Preference: return-accepted</t>
<t>Description: Indicates that the user-agent prefers
the server to respond with a 202 Accepted status as described
by <xref target="return-accepted" /></t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: return-no-content</t>
<t>Description: Indicates that the user-agent prefers
the server not to include a payload in response to a
request as described by <xref target="return-no-content" /></t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: return-content</t>
<t>Description: Indicates that the user-agent prefers
the server to include a representation of the current state
of the resource in response to a request as described by
<xref target="return-content"/></t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: return-status</t>
<t>Description: Indicates that the user-agent prefers
the server to return an entity describing the current
state of a resource in response to a request as
described by <xref target="return-status" /></t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: wait</t>
<t>Description: Indicates an upper bound to the lenght of
time the user-agent is willing to wait for a response, after which
the request may be aborted.</t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: priority</t>
<t>Description: Indicates the priority a client wishes the
server to assign to the processing of a request relative to
other concurrently processed requests.</t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: strict</t>
<t>Description: Indicates that the client wishes the server
to apply strict validation and error handling to the processing
of a request.</t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: lenient</t>
<t>Description: Indicates that the client wishes the server
to apply lenient validation and error handling to the processing
of a request.</t>
<t>Reference: [this specification]</t>
</list>
</t>
<t>
<list style="symbols">
<t>Preference: detail</t>
<t>Description: Indicates the user-agent's preference as to the amount
of detail the server should include in responses to a request.</t>
<t>Reference: [this specification]</t>
</list>
</t>
</section>
</section>
</section>
<section title="Security Considerations">
<t>Specific preferences requested by a client can introduce security
considerations and concerns beyond those discussed in <xref target="RFC2616" />.
Implementors must refer to the specifications and descriptions of those
preferences to determine the security considerations relevant to each.</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc2434;
&rfc2616;
&rfc3864;
&rfc5226;
&rfc2026;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 04:05:15 |