[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                                            March 28, 2011
Intended status: Informational
Expires: September 29, 2011


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

Abstract

   This specification defines an HTTP header that can be used by a
   client 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 September 29, 2011.

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 September 29, 2011               [Page 1]

Internet-Draft                 HTTP Prefer                    March 2011


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
   2.  The Prefer Request Header . . . . . . . . . . . . . . . . . . . 3
   3.  The Preference-Applied Response Header  . . . . . . . . . . . . 4
   4.  The "return-accepted" Preference  . . . . . . . . . . . . . . . 4
   5.  The "return-content" Preference . . . . . . . . . . . . . . . . 4
   6.  The "return-no-content" Preference  . . . . . . . . . . . . . . 4
   7.  The "return-status" Preference  . . . . . . . . . . . . . . . . 4
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4
     8.1.  The Registry of Preferences . . . . . . . . . . . . . . . . 5
   9.  Security Considerations . . . . . . . . . . . . . . . . . . . . 5
   10. Normative References  . . . . . . . . . . . . . . . . . . . . . 5
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 6





































Snell                  Expires September 29, 2011               [Page 2]

Internet-Draft                 HTTP Prefer                    March 2011


1.  Introduction

   This specification defines a new HTTP header that can be used by a
   client to request that certain behaviors be implemented by a server
   while processing a 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 client, 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-no-content" |
                     "return-content" |
                     "return-status" |
                     preference-extension
     preference-extension =  token [ "=" ( token | quoted-string )
                             *prefer-params ]
     prefer-params =  ";" token [ "=" ( token | quoted-string ) ]

   This header is defined with an extensible syntax to allow for future
   values included in the Registry of Preferences (Section 8.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.

   Comparison of preference values is case-insensitive for unquoted
   tokens and is case-sensitive for quoted-string preference-extensions.

   An HTTP proxy MAY choose to honor a preference even if the origin
   server does not.  The Prefer request-header MUST be forwarded by the
   proxy if the request is forwarded.

   Note that the application of a preference by the server MAY affect
   the caching characteristics of the response.







Snell                  Expires September 29, 2011               [Page 3]

Internet-Draft                 HTTP Prefer                    March 2011


3.  The Preference-Applied Response Header

   The Preference-Applied response header MAY be included in the
   response message to indicate which Prefer request header values were
   honored by the server and applied to the request.

     Preference-Applied  =  "Preference-Applied" ":" 1#preference


4.  The "return-accepted" Preference

   The "return-accepted" token indicates that the client prefers that
   the server respond with a 202 Accepted response indicating that the
   request has been accepted for processing.


5.  The "return-content" Preference

   The "return-content" token indicates that the client prefers that the
   server include an entity representing the current state of the
   resource in the response to a successful request.


6.  The "return-no-content" Preference

   The "return-no-content" token indicates that the client prefers that
   the server not include an entity in the response to a successful
   request.  Typically, such responses would use the 204 No Content
   status code as defined in Section 10.2.5 of [RFC2616], but other
   status codes can be used as appropriate.


7.  The "return-status" Preference

   The "return-status" token indicates that the client prefers that the
   server include an entity describing the status of the request in the
   response to a successful request.


8.  IANA Considerations

   The 'Prefer' and 'Preference-Applied' headers should be added to the
   permanent registry (see [RFC3864]).








Snell                  Expires September 29, 2011               [Page 4]

Internet-Draft                 HTTP Prefer                    March 2011


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

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

8.1.  The Registry of Preferences

   This registry is maintained by IANA and initially contains the
   values: "return-accepted", "return-content", "return-no-content" and
   "return-status".  New assignments are subjects to IESG approval, as
   outlined in [RFC2434].  Requests should be made by email to IANA,
   which will then forward the request to the IESG, requesting approval.
   The request should use the following template:

   o  Preference: (A value for the Prefer request header that conforms
      to the syntax rule given in Section 2)
   o  Description:
   o  Expected server behavior:
   o  Security considerations:


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


10.  Normative References

   [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



Snell                  Expires September 29, 2011               [Page 5]

Internet-Draft                 HTTP Prefer                    March 2011


              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.


Author's Address

   James M Snell


   Phone:
   Email: jasnell@gmail.com
   URI:




































Snell                  Expires September 29, 2011               [Page 6]


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