One document matched: draft-snell-http-prefer-03.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'> 
]>
<?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-03"> 
  <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="March" 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 client 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 header that can be
      used by a client to request that certain behaviors be implemented
      by a server while processing a 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 client, 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-no-content" |
                  "return-content" | 
                  "return-status" | 
                  preference-extension
  preference-extension =  token [ "=" ( token | quoted-string )
                          *prefer-params ]
  prefer-params =  ";" token [ "=" ( token | quoted-string ) ]
      </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>Comparison of preference values is case-insensitive for unquoted 
      tokens and is case-sensitive for quoted-string preference-extensions.</t> 
      
      <t>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.</t> 
    
      <t>Note that the application of a preference by the server MAY affect 
      the caching characteristics of the response.</t>
       
    </section> 
     
    <section title="The Preference-Applied Response Header"> 
    
      <t>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.</t> 
 
      <figure><artwork> 
  Preference-Applied  =  "Preference-Applied" ":" 1#preference
      </artwork></figure> 
    
    </section> 

    <section title="The "return-accepted" Preference">
      <t>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.</t>
    </section>

    <section title="The "return-content" Preference"> 
      <t>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.</t>     
    </section> 
     
    <section title="The "return-no-content" Preference"> 
      <t>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 <xref target="RFC2616" />, but other status
      codes can be used as appropriate.</t> 
    </section> 
          
    <section title="The "return-status" Preference"> 
      <t>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.</t> 
    </section> 
      
    <section title="IANA Considerations"> 
 
      <t>The 'Prefer' and 'Preference-Applied' headers 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
    
    Header field name: Preference-Applied
    Applicable Protocol: HTTP
    Status: 
    Author/Change controller: IETF
    Specification document: this specification
    </artwork></figure></t> 
      
      <section title="The Registry of Preferences" anchor="registry"> 
        <t>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 <xref target="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:</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>Expected server behavior:</t> 
            <t>Security considerations:</t> 
          </list> 
        </t> 
      </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;
    </references>
  </back>
</rfc>