[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 RFC 7240

Individual Submission                                           J. Snell
Internet-Draft                                          October 25, 2011
Intended status: Informational
Expires: April 27, 2012


                         Prefer Header for HTTP
                       draft-snell-http-prefer-04

Abstract

   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.

Status of this Memo

   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 Notice

   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.





Snell                    Expires April 27, 2012                 [Page 1]

Internet-Draft                 HTTP Prefer                  October 2011


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  The Prefer Request Header  . . . . . . . . . . . . . . . . . .  3
   3.  The "return-accepted" Preference . . . . . . . . . . . . . . .  4
   4.  The "return-content" Preference  . . . . . . . . . . . . . . .  4
   5.  The "return-status" Preference . . . . . . . . . . . . . . . .  5
   6.  The "return-no-content" Preference . . . . . . . . . . . . . .  5
   7.  The "wait" Preference  . . . . . . . . . . . . . . . . . . . .  6
   8.  The "priority" Preference  . . . . . . . . . . . . . . . . . .  6
   9.  The "strict" and "lenient" Processing Preferences  . . . . . .  7
   10. The "detail" Preference  . . . . . . . . . . . . . . . . . . .  7
   11. Registered Preferences . . . . . . . . . . . . . . . . . . . .  8
   12. IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  8
     12.1.  The Registry of Preferences . . . . . . . . . . . . . . .  8
       12.1.1.  Initial Registry Contents . . . . . . . . . . . . . .  9
   13. Security Considerations  . . . . . . . . . . . . . . . . . . . 11
   14. Normative References . . . . . . . . . . . . . . . . . . . . . 11
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11
































Snell                    Expires April 27, 2012                 [Page 2]

Internet-Draft                 HTTP Prefer                  October 2011


1.  Introduction

   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.

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
   and "OPTIONAL" are to be interpreted as described in [RFC2119].


2.  The Prefer Request Header

   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.




Snell                    Expires April 27, 2012                 [Page 3]

Internet-Draft                 HTTP Prefer                  October 2011


   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.


3.  The "return-accepted" Preference

   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.


4.  The "return-content" Preference

   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



Snell                    Expires April 27, 2012                 [Page 4]

Internet-Draft                 HTTP Prefer                  October 2011


   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.


5.  The "return-status" Preference

   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.


6.  The "return-no-content" Preference

   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"




Snell                    Expires April 27, 2012                 [Page 5]

Internet-Draft                 HTTP Prefer                  October 2011


   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.


7.  The "wait" Preference

   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


8.  The "priority" Preference

   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.




Snell                    Expires April 27, 2012                 [Page 6]

Internet-Draft                 HTTP Prefer                  October 2011


9.  The "strict" and "lenient" Processing Preferences

   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"


10.  The "detail" Preference

   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.



Snell                    Expires April 27, 2012                 [Page 7]

Internet-Draft                 HTTP Prefer                  October 2011


   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).


11.  Registered Preferences

   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.


12.  IANA Considerations

   The 'Prefer' header should be added to the permanent registry (see
   [RFC3864]).


       Header field name: Prefer
       Applicable Protocol: HTTP
       Status:
       Author/Change controller: IETF
       Specification document: this specification


12.1.  The Registry of Preferences

   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]).



Snell                    Expires April 27, 2012                 [Page 8]

Internet-Draft                 HTTP Prefer                  October 2011


   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:

   o  Preference: (A value for the Prefer request header that conforms
      to the syntax rule given in Section 2)
   o  Description:
   o  Reference:
   o  Notes: [optional]
   o  Application Data: [optional]

   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.

12.1.1.  Initial Registry Contents

   The Preferences Registry's initial contents are:




Snell                    Expires April 27, 2012                 [Page 9]

Internet-Draft                 HTTP Prefer                  October 2011


   o  Preference: return-accepted
   o  Description: Indicates that the user-agent prefers the server to
      respond with a 202 Accepted status as described by Section 3
   o  Reference: [this specification]

   o  Preference: return-no-content
   o  Description: Indicates that the user-agent prefers the server not
      to include a payload in response to a request as described by
      Section 6
   o  Reference: [this specification]

   o  Preference: return-content
   o  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 Section 4
   o  Reference: [this specification]

   o  Preference: return-status
   o  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 Section 5
   o  Reference: [this specification]

   o  Preference: wait
   o  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.
   o  Reference: [this specification]

   o  Preference: priority
   o  Description: Indicates the priority a client wishes the server to
      assign to the processing of a request relative to other
      concurrently processed requests.
   o  Reference: [this specification]

   o  Preference: strict
   o  Description: Indicates that the client wishes the server to apply
      strict validation and error handling to the processing of a
      request.
   o  Reference: [this specification]

   o  Preference: lenient
   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]





Snell                    Expires April 27, 2012                [Page 10]

Internet-Draft                 HTTP Prefer                  October 2011


   o  Preference: detail
   o  Description: Indicates the user-agent's preference as to the
      amount of detail the server should include in responses to a
      request.
   o  Reference: [this specification]


13.  Security Considerations

   Specific preferences requested by a client can introduce security
   considerations and concerns beyond those discussed in [RFC2616].
   Implementors must refer to the specifications and descriptions of
   those preferences to determine the security considerations relevant
   to each.


14.  Normative References

   [RFC2026]  Bradner, S., "The Internet Standards Process -- Revision
              3", BCP 9, RFC 2026, October 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2434]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 2434,
              October 1998.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
              Procedures for Message Header Fields", BCP 90, RFC 3864,
              September 2004.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              May 2008.












Snell                    Expires April 27, 2012                [Page 11]

Internet-Draft                 HTTP Prefer                  October 2011


Author's Address

   James M Snell


   Phone:
   Email: jasnell@gmail.com
   URI:











































Snell                    Expires April 27, 2012                [Page 12]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/