idnits 2.17.1 draft-snell-http-prefer-05.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 (December 6, 2011) is 4524 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC2434' is defined on line 453, but no explicit reference was found in the text == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-17 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-17 ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 10 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 December 6, 2011 4 Intended status: Informational 5 Expires: June 8, 2012 7 Prefer Header for HTTP 8 draft-snell-http-prefer-05 10 Abstract 12 This specification defines an HTTP header field that can be used by a 13 user-agent to request that certain behaviors be implemented by a 14 server 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 June 8, 2012. 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 "return-accepted" Preference . . . . . . . . . . . . . . . 4 53 4. The "return-representation" Preference . . . . . . . . . . . . 4 54 5. The "return-status" Preference . . . . . . . . . . . . . . . . 5 55 6. The "return-minimal" Preference . . . . . . . . . . . . . . . 5 56 7. The "wait" Preference . . . . . . . . . . . . . . . . . . . . 6 57 8. The "strict" and "lenient" Processing Preferences . . . . . . 6 58 9. Registered Preferences . . . . . . . . . . . . . . . . . . . . 7 59 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 60 10.1. The Registry of Preferences . . . . . . . . . . . . . . . 7 61 10.1.1. Initial Registry Contents . . . . . . . . . . . . . . 8 62 11. Security Considerations . . . . . . . . . . . . . . . . . . . 9 63 12. Normative References . . . . . . . . . . . . . . . . . . . . . 10 64 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 1. Introduction 68 This specification defines a new HTTP request header field that may 69 be used by user-agents to request optional behaviors be applied by a 70 server during the processing the request. 72 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 73 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 74 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 76 2. The Prefer Request Header 78 The Prefer request-header field is used to indicate that particular 79 server behaviors are preferred by the user-agent, but not required 80 for successful completion of the request. Prefer is similar in 81 nature to the Expect header field defined by 82 [I-D.ietf-httpbis-p2-semantics] Section 9.3 with the exception that 83 servers are allowed to ignore stated preferences. 85 Prefer = "Prefer" ":" 1#preference 86 preference = OWS preference-token OWS *prefer-params OWS 87 preference-value = token / quoted-string 88 preference-token = token OWS [ "=" OWS preference-value OWS ] 89 prefer-params = ";" OWS preference-token 91 This header field is defined with an extensible syntax to allow for 92 future values included in the Registry of Preferences 93 (Section 10.1)). A server that does not recognize or is unable to 94 comply with particular preference values in the Prefer header field 95 of a request MUST ignore those values and MUST NOT stop processing or 96 signal an error. 98 A preference token MAY specify a preference-value. Empty, or zero 99 length preference-values on both the preference directive and 100 parameters are equivalent to no value being specified at all. The 101 following, then, are equivalent: 103 Prefer: foo; bar="" 104 Prefer: foo=; bar 105 Prefer: foo=""; bar= 107 An optional, arbitrary collection of preference parameters MAY be 108 specified for any preference directive. The meaning and application 109 of such parameters is dependent on the definition of each preference 110 directive and the server's implementation thereof. 112 If a particular preference directive or parameter is specified 113 multiple times, repeated occurrences MUST be ignored without 114 signaling an error or otherwise altering the processing of the 115 request. 117 Comparison of preference token names is case-insensitive while values 118 are case-sensitive regardless of whether token or quoted-string 119 values are used. 121 Note that the application of a preference by the server MAY affect 122 the caching characteristics of the response. Specifically, should 123 the application of a preference result in a variance to the 124 representation returned by a cacheable response, a Vary header field 125 MUST be included listing the Prefer header field as one of the 126 selecting header fields. 128 The Prefer request header field MUST be forwarded by the proxy if the 129 request is forwarded. In various situations, A proxy may determine 130 that it is capable of honoring a preference independently of the 131 server to which the request is directed. For instance, an 132 intervening proxy may be capable of transparently providing 133 asynchronous handling of a request using a 202 Accepted responses 134 independently of the origin server. Such proxies could choose to 135 honor the "return-accepted" preference. Individual preference 136 directives MAY define their own requirements and restrictions as to 137 whether and how proxies may apply the preference to a request 138 independently of the origin server. 140 3. The "return-accepted" Preference 142 The "return-accepted" preference indicates that the user-agent 143 prefers the server to respond with a 202 Accepted status in the case 144 where the length of time it takes to generate a response will exceed 145 some arbitrary threshold established by the server. 147 return-accepted = "return-accepted" 149 The key motivation for the "return-accepted" preference is to 150 facilitate the operation of asynchronous request handling by allowing 151 the user-agent to indicate to a server it's capability and preference 152 for handling 202 Accepted responses. 154 4. The "return-representation" Preference 156 The "return-representation" preference indicates that the user-agent 157 prefers that the server include an entity representing the current 158 state of the resource in the response to a successful request. 160 return-representation = "return-representation" 162 When honoring the "return-representation" preference, the server MUST 163 include a Content-Location header field specifying the URI of the 164 resource representation being returned. Per section 6.1 of 165 [I-D.ietf-httpbis-p2-semantics], the presence of the Content-Location 166 header field in the response asserts that the payload is a 167 representation of the resource identified by the Content-Location 168 URI. 170 The "return-representation" preference is intended primarily to 171 provide a means of optimizing communication between the user-agent 172 and server by eliminating the need for a subsequent GET request to 173 retrieve the current representation of the resource following a 174 modification. 176 Currently, after successfully processing a modification request such 177 as a POST or PUT, a server may choose to return either an entity 178 describing the status of the operation or a representation of the 179 modified resource itself. While the selection of which type of 180 entity to return, if any at all, is solely at the discretion of the 181 server, the "return-representation" preference -- along with the 182 "return-status" and "return-minimal" directives defined below -- 183 allow the server to take the user-agent's preferences into 184 consideration while constructing the response. 186 5. The "return-status" Preference 188 The "return-status" preference indicates that the user-agent prefers 189 the server to include an entity describing the status of the request 190 in the response as opposed to returning a representation of the 191 current state of the resource. 193 return-status = "return-status" 195 When honoring the "return-status" preference, the server SHOULD NOT 196 include a Content-Location header field in the response. 198 6. The "return-minimal" Preference 200 The "return-minimal" preference indicates that the user-agent wishes 201 the server to return a minimal response to a successful request. 202 Typically, such responses would utilize the 204 No Content status, 203 but other codes MAY be used as appropriate, such as a 200 status with 204 a zero-length response entity. The determination of what constitutes 205 an appropriate minimal response is solely at the discretion of the 206 server. 208 return-minimal = "return-minimal" 210 The "return-minimal" preference is intended to provide a means of 211 optimizing communication between the user-agent and server by 212 reducing the amount of data the server is required to return to the 213 user-agent following a request. This can be particularly useful, for 214 instance, when communicating with limited-bandwidth mobile devices or 215 when the user-agent simply does not require any further information 216 about the result of a request beyond knowing if it was successfully 217 processed. 219 7. The "wait" Preference 221 The "wait" preference can be used to establish an upper bound on the 222 length of time, in seconds, the user-agent is willing to wait for a 223 response, after which the user-agent may choose to abandon the 224 request. In the case generating a response will take longer than the 225 time specified, the server, or proxy, can choose to either return a 226 202 Accepted response, cancel processing, or continue attempting to 227 complete the request. 229 wait = "wait" OWS "=" OWS delta-seconds 231 User-Agents specifying the "wait" Preference SHOULD also use the Date 232 header field, as specified in [I-D.ietf-httpbis-p2-semantics] Section 233 9.2, within the request to establish the time at which the client 234 began waiting for the completion of the request. 236 8. The "strict" and "lenient" Processing Preferences 238 ED NOTE: This preference directive is currently exploratory in 239 nature. I've added it to solicit feedback as to it's general 240 utility. It is possible that I may pull this back out. 242 The "strict" and "lenient" preferences are mutually-exclusive 243 directives indicating, at the servers discretion, how the user-agent 244 wishes the server to handle potential error conditions that may arise 245 in the processing of a request. For instance, if the payload of a 246 request contains various minor syntactical or semantic errors, but 247 the server is still capable of comprehending and successfully 248 processing the request, a decision must be made to either reject the 249 request with an appropriate 4xx error response or to go ahead with 250 processing. The "strict" preference can be used by the user-agent to 251 indicate that, in such conditions, it would prefer that the server 252 reject the request, while the "lenient" preference indicates that the 253 user-agent would prefer the server to attempt to process the request. 254 The specific meaning and application of the "strict" and "lenient" 255 directives is specific to each type of resource, the request method 256 and the operation of the server. 258 handling = "strict" / "lenient" 260 9. Registered Preferences 262 Well-defined preferences can be registered for convenience and/or to 263 promote reuse by other applications. This specification establishes 264 an IANA registry of such relation types see Section Section 10.1. 266 Registered preference names MUST conform to the token rule, and MUST 267 be compared character-by-character in a case-insensitive fashion. 268 They SHOULD be appropriate to the specificity of the preference; 269 i.e., if the semantics are highly specific to a particular 270 application, the name should reflect that, so that more general names 271 are available for less specific use. 273 Registered preferences MUST NOT constrain servers, user-agents or any 274 intermediaries involved in the exchange and processing of a request 275 to any behavior required for successful processing. The use and 276 application of a preference within a given request MUST be optional 277 on the part of all participants. 279 10. IANA Considerations 281 The 'Prefer' header field should be added to the permanent registry 282 (see [RFC3864]). 284 Header field name: Prefer 285 Applicable Protocol: HTTP 286 Status: 287 Author/Change controller: IETF 288 Specification document: this specification 290 10.1. The Registry of Preferences 292 Preferences are registered on the advice of a Designated Expert 293 (appointed by the IESG or their delegate), with a Specification 294 Required (using terminology from [RFC5226]). 296 The requirements for registered preferences are described in 297 Section 9 299 Registration requests consist of the completed registration template 300 below, typically published in an RFC or Open Standard (in the sense 301 described by [RFC2026], Section 7). However, to allow for the 302 allocation of values prior to publication, the Designated Expert may 303 approve registration once they are satisfied that a specification 304 will be published. 306 Note that relation types can be registered by third parties, if the 307 Designated Expert determines that an unregistered relation type is 308 widely deployed and not likely to be registered in a timely manner. 310 The registration template is: 312 o Preference: (A value for the Prefer request header field that 313 conforms to the syntax rule given in Section 2) 314 o Description: 315 o Reference: 316 o Notes: [optional] 317 o Application Data: [optional] 319 Registration requests should be sent to the preferences@ietf.org 320 mailing list, marked clearly in the subject line (e.g., "NEW 321 PREFERENCE - example" to register an "example" preference). 323 Within at most 14 days of the request, the Designated Expert(s) will 324 either approve or deny the registration request, communicating this 325 decision to the review list and IANA. Denials should include an 326 explanation and, if applicable, suggestions as to how to make the 327 request successful. 329 Decisions (or lack thereof) made by the Designated Expert can be 330 first appealed to Application Area Directors (contactable using 331 app-ads@tools.ietf.org email address or directly by looking up their 332 email addresses on http://www.iesg.org/ website) and, if the 333 appellant is not satisfied with the response, to the full IESG (using 334 the iesg@iesg.org mailing list). 336 IANA should only accept registry updates from the Designated 337 Expert(s), and should direct all requests for registration to the 338 review mailing list. 340 10.1.1. Initial Registry Contents 342 The Preferences Registry's initial contents are: 344 o Preference: return-accepted 345 o Description: Indicates that the user-agent prefers the server to 346 respond with a 202 Accepted status as described by Section 3 347 o Reference: [this specification] 349 o Preference: return-minimal 350 o Description: Indicates that the user-agent prefers the server 351 return a minimal response to a request as described by Section 6 352 o Reference: [this specification] 354 o Preference: return-representation 355 o Description: Indicates that the user-agent prefers the server to 356 include a representation of the current state of the resource in 357 response to a request as described by Section 4 358 o Reference: [this specification] 360 o Preference: return-status 361 o Description: Indicates that the user-agent prefers the server to 362 return an entity describing the current state of a resource in 363 response to a request as described by Section 5 364 o Reference: [this specification] 366 o Preference: wait 367 o Description: Indicates an upper bound to the lenght of time the 368 user-agent is willing to wait for a response, after which the 369 request may be aborted. 370 o Reference: [this specification] 372 o Preference: strict 373 o Description: Indicates that the client wishes the server to apply 374 strict validation and error handling to the processing of a 375 request. 376 o Reference: [this specification] 378 o Preference: lenient 379 o Description: Indicates that the client wishes the server to apply 380 lenient validation and error handling to the processing of a 381 request. 382 o Reference: [this specification] 384 11. Security Considerations 386 Specific preferences requested by a client can introduce security 387 considerations and concerns beyond those discussed in HTTP/1.1 Parts 388 1 [I-D.ietf-httpbis-p1-messaging], 2 [I-D.ietf-httpbis-p2-semantics], 389 3 [I-D.ietf-httpbis-p3-payload], 4 [I-D.ietf-httpbis-p4-conditional], 390 5 [I-D.ietf-httpbis-p5-range], 6 [I-D.ietf-httpbis-p6-cache], and 7 392 [I-D.ietf-httpbis-p7-auth]. Implementors must refer to the 393 specifications and descriptions of each preference to determine the 394 security considerations relevant to each. 396 12. Normative References 398 [I-D.ietf-httpbis-p1-messaging] 399 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 400 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 401 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 402 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 403 in progress), October 2011. 405 [I-D.ietf-httpbis-p2-semantics] 406 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 407 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 408 J. Reschke, "HTTP/1.1, part 2: Message Semantics", 409 draft-ietf-httpbis-p2-semantics-17 (work in progress), 410 October 2011. 412 [I-D.ietf-httpbis-p3-payload] 413 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 414 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 415 J. Reschke, "HTTP/1.1, part 3: Message Payload and Content 416 Negotiation", draft-ietf-httpbis-p3-payload-17 (work in 417 progress), October 2011. 419 [I-D.ietf-httpbis-p4-conditional] 420 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 421 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 422 J. Reschke, "HTTP/1.1, part 4: Conditional Requests", 423 draft-ietf-httpbis-p4-conditional-17 (work in progress), 424 October 2011. 426 [I-D.ietf-httpbis-p5-range] 427 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 428 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 429 J. Reschke, "HTTP/1.1, part 5: Range Requests and Partial 430 Responses", draft-ietf-httpbis-p5-range-17 (work in 431 progress), October 2011. 433 [I-D.ietf-httpbis-p6-cache] 434 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 435 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., 436 Nottingham, M., and J. Reschke, "HTTP/1.1, part 6: 437 Caching", draft-ietf-httpbis-p6-cache-17 (work in 438 progress), October 2011. 440 [I-D.ietf-httpbis-p7-auth] 441 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 442 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 443 J. Reschke, "HTTP/1.1, part 7: Authentication", 444 draft-ietf-httpbis-p7-auth-17 (work in progress), 445 October 2011. 447 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 448 3", BCP 9, RFC 2026, October 1996. 450 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 451 Requirement Levels", BCP 14, RFC 2119, March 1997. 453 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 454 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 455 October 1998. 457 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 458 Procedures for Message Header Fields", BCP 90, RFC 3864, 459 September 2004. 461 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 462 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 463 May 2008. 465 Author's Address 467 James M Snell 469 Phone: 470 Email: jasnell@gmail.com 471 URI: