idnits 2.17.1 draft-snell-http-prefer-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 28, 2011) is 4777 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Individual Submission J. Snell 3 Internet-Draft March 28, 2011 4 Intended status: Informational 5 Expires: September 29, 2011 7 Prefer Header for HTTP 8 draft-snell-http-prefer-03 10 Abstract 12 This specification defines an HTTP header that can be used by a 13 client to request that certain behaviors be implemented by a server 14 while processing a request. 16 Status of this Memo 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on September 29, 2011. 33 Copyright Notice 35 Copyright (c) 2011 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. The Prefer Request Header . . . . . . . . . . . . . . . . . . . 3 52 3. The Preference-Applied Response Header . . . . . . . . . . . . 4 53 4. The "return-accepted" Preference . . . . . . . . . . . . . . . 4 54 5. The "return-content" Preference . . . . . . . . . . . . . . . . 4 55 6. The "return-no-content" Preference . . . . . . . . . . . . . . 4 56 7. The "return-status" Preference . . . . . . . . . . . . . . . . 4 57 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 58 8.1. The Registry of Preferences . . . . . . . . . . . . . . . . 5 59 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 60 10. Normative References . . . . . . . . . . . . . . . . . . . . . 5 61 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 1. Introduction 65 This specification defines a new HTTP header that can be used by a 66 client to request that certain behaviors be implemented by a server 67 while processing a request. 69 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 70 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 71 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 73 2. The Prefer Request Header 75 The Prefer request-header is used to indicate that particular server 76 behaviors are preferred by the client, but not required for 77 successful completion of the request. Prefer is similar in nature to 78 the Expect header defined by [RFC2616] with the exception that 79 servers are allowed to ignore stated preferences. 81 Prefer = "Prefer" ":" 1#preference 83 preference = "return-no-content" | 84 "return-content" | 85 "return-status" | 86 preference-extension 87 preference-extension = token [ "=" ( token | quoted-string ) 88 *prefer-params ] 89 prefer-params = ";" token [ "=" ( token | quoted-string ) ] 91 This header is defined with an extensible syntax to allow for future 92 values included in the Registry of Preferences (Section 8.1)). A 93 server that does not recognize or is unable to comply with particular 94 preference values in the Prefer header of a request MUST ignore those 95 values and MUST NOT stop processing or signal an error. 97 Comparison of preference values is case-insensitive for unquoted 98 tokens and is case-sensitive for quoted-string preference-extensions. 100 An HTTP proxy MAY choose to honor a preference even if the origin 101 server does not. The Prefer request-header MUST be forwarded by the 102 proxy if the request is forwarded. 104 Note that the application of a preference by the server MAY affect 105 the caching characteristics of the response. 107 3. The Preference-Applied Response Header 109 The Preference-Applied response header MAY be included in the 110 response message to indicate which Prefer request header values were 111 honored by the server and applied to the request. 113 Preference-Applied = "Preference-Applied" ":" 1#preference 115 4. The "return-accepted" Preference 117 The "return-accepted" token indicates that the client prefers that 118 the server respond with a 202 Accepted response indicating that the 119 request has been accepted for processing. 121 5. The "return-content" Preference 123 The "return-content" token indicates that the client prefers that the 124 server include an entity representing the current state of the 125 resource in the response to a successful request. 127 6. The "return-no-content" Preference 129 The "return-no-content" token indicates that the client prefers that 130 the server not include an entity in the response to a successful 131 request. Typically, such responses would use the 204 No Content 132 status code as defined in Section 10.2.5 of [RFC2616], but other 133 status codes can be used as appropriate. 135 7. The "return-status" Preference 137 The "return-status" token indicates that the client prefers that the 138 server include an entity describing the status of the request in the 139 response to a successful request. 141 8. IANA Considerations 143 The 'Prefer' and 'Preference-Applied' headers should be added to the 144 permanent registry (see [RFC3864]). 146 Header field name: Prefer 147 Applicable Protocol: HTTP 148 Status: 149 Author/Change controller: IETF 150 Specification document: this specification 152 Header field name: Preference-Applied 153 Applicable Protocol: HTTP 154 Status: 155 Author/Change controller: IETF 156 Specification document: this specification 158 8.1. The Registry of Preferences 160 This registry is maintained by IANA and initially contains the 161 values: "return-accepted", "return-content", "return-no-content" and 162 "return-status". New assignments are subjects to IESG approval, as 163 outlined in [RFC2434]. Requests should be made by email to IANA, 164 which will then forward the request to the IESG, requesting approval. 165 The request should use the following template: 167 o Preference: (A value for the Prefer request header that conforms 168 to the syntax rule given in Section 2) 169 o Description: 170 o Expected server behavior: 171 o Security considerations: 173 9. Security Considerations 175 Specific preferences requested by a client can introduce security 176 considerations and concerns beyond those discussed in [RFC2616]. 177 Implementors must refer to the specifications and descriptions of 178 those preferences to determine the security considerations relevant 179 to each. 181 10. Normative References 183 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 184 Requirement Levels", BCP 14, RFC 2119, March 1997. 186 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 187 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 188 October 1998. 190 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 191 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 192 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 194 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 195 Procedures for Message Header Fields", BCP 90, RFC 3864, 196 September 2004. 198 Author's Address 200 James M Snell 202 Phone: 203 Email: jasnell@gmail.com 204 URI: