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.

Table of Contents

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

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

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.

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

 
    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:

• Preference: (A value for the Prefer request header that conforms to the syntax rule given in Section 2)
• Description:
• Expected server behavior:
• 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. References

Author's Address