One document matched: draft-snell-http-prefer-02.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 ipr="full3978" docName="draft-snell-http-prefer-02">
  <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>http://www.snellspace.com</uri>
      </address>
    </author>
    
    <date month="February" year="2008" />

    <area>Applications</area>
    <workgroup>Individual Submission</workgroup>
    <keyword>I-D</keyword>
    <keyword>http</keyword>
    <keyword>prefer</keyword>

    <abstract>
      <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>
    </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, but not required, by the client.  Prefer
      is similar in nature to the Expect header defined by <xref target="RFC2616" /> 
      with the exception that servers are allowed to ignore a clients 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 Registry of Preferences (see <xref target="registry" />). 
      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>
      
    </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>
  Prefer       =  "Preference-Applied" ":" 1#preference
      </artwork></figure>
    
    </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-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-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' request header should be added to the permanent 
      registry (see <xref target="RFC3864" />).</t>
        
    <t><figure><artwork>
    Header field name: Prefer
    
    Applicable Protocol: HTTP
    
    Status: standard
    
    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 three
        values: "return-no-content", "return-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>
    
    <section title="Acknowledgements">
      <t>The author greatfully acknowledges the input from the IETF HTTP
      mailing list on the development of this document.</t>

    </section>
    <section title="Changes">
      <t>TODO</t>            
    </section>
      
    <section title="Notes to RFC Editor">
      <t>The RFC Editor should remove this section and the Changes section.</t>
    </section>
    
    <section title="Editorial Notes">
      <t>We need to determine how new preference codes are created/registered</t>
    </section>
    
  </back>

</rfc>