idnits 2.17.1 draft-snell-http-prefer-07.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 8, 2011) is 4524 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == 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 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Individual Submission J. Snell 3 Internet-Draft December 8, 2011 4 Intended status: Informational 5 Expires: June 10, 2012 7 Prefer Header for HTTP 8 draft-snell-http-prefer-07 10 Abstract 12 This specification defines an HTTP header field 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 June 10, 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 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 3 52 2. The Prefer Request Header . . . . . . . . . . . . . . . . . . 3 53 2.1. Cache Considerations . . . . . . . . . . . . . . . . . . . 4 54 2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 3. The "return-accepted" Preference . . . . . . . . . . . . . . . 5 56 4. The "return-representation" Preference . . . . . . . . . . . . 6 57 5. The "return-minimal" Preference . . . . . . . . . . . . . . . 6 58 6. The "wait" Preference . . . . . . . . . . . . . . . . . . . . 7 59 7. The "strict" and "lenient" Processing Preferences . . . . . . 7 60 8. Registered Preferences . . . . . . . . . . . . . . . . . . . . 8 61 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 9.1. The Registry of Preferences . . . . . . . . . . . . . . . 8 63 9.1.1. Initial Registry Contents . . . . . . . . . . . . . . 9 64 10. Security Considerations . . . . . . . . . . . . . . . . . . . 10 65 11. Normative References . . . . . . . . . . . . . . . . . . . . . 10 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 1. Introduction 70 This specification defines a new HTTP request header field that may 71 be used by clients to request optional behaviors be applied by a 72 server during the processing the request. 74 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 75 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 76 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 78 1.1. Syntax Notation 80 This specification uses the Augmented Backus-Naur Form (ABNF) 81 notation of [RFC5234] and includes, by reference, the "token", 82 "quoted-string", "OWS", "BWS" rules and the #rule extension as 83 defined within [I-D.ietf-httpbis-p1-messaging] Section 1.2. 85 2. The Prefer Request Header 87 The Prefer request-header field is used to indicate that particular 88 server behaviors are preferred by the client, but not required for 89 successful completion of the request. Prefer is similar in nature to 90 the Expect header field defined by [I-D.ietf-httpbis-p2-semantics] 91 Section 9.3 with the exception that servers are allowed to ignore 92 stated preferences. 94 Prefer = "Prefer" ":" 1#preference 95 preference = token [ BWS "=" BWS value ] 96 *( OWS ";" [ OWS parameter ] ) 97 parameter = token [ BWS "=" BWS value ] 98 value = token / quoted-string 100 This header field is defined with an extensible syntax to allow for 101 future values included in the Registry of Preferences (Section 9.1)). 102 A server that does not recognize or is unable to comply with 103 particular preference tokens in the Prefer header field of a request 104 MUST ignore those tokens and MUST NOT stop processing or signal an 105 error. 107 A preference token MAY specify a value. Empty, or zero length values 108 on both the preference token and within parameters are equivalent to 109 no value being specified at all. The following, then, are 110 equivalent: 112 Prefer: foo; bar="" 113 Prefer: foo=; bar 114 Prefer: foo=""; bar= 116 An optional, arbitrary collection of parameters MAY be specified for 117 any preference token. The meaning and application of such parameters 118 is dependent on the definition of each preference token and the 119 server's implementation thereof. 121 If a particular preference token or parameter is specified multiple 122 times, repeated occurrences MUST be ignored without signaling an 123 error or otherwise altering the processing of the request. 125 Comparison of preference token names is case-insensitive while values 126 are case-sensitive regardless of whether token or quoted-string 127 values are used. 129 The Prefer request header field MUST be forwarded by a proxy if the 130 request is forwarded. In various situations, A proxy may determine 131 that it is capable of honoring a preference independently of the 132 server to which the request is directed. For instance, an 133 intervening proxy may be capable of transparently providing 134 asynchronous handling of a request using a 202 Accepted responses 135 independently of the origin server. Such proxies could choose to 136 honor the "return-accepted" preference. Individual preference tokens 137 MAY define their own requirements and restrictions as to whether and 138 how proxies may apply the preference to a request independently of 139 the origin server. 141 As per [I-D.ietf-httpbis-p1-messaging], Section 3.2, Implementations 142 MUST be capable of supporting either multiple instances of the Prefer 143 header field in a single message as well as multiple preference 144 tokens separated by commas in a single Prefer header, for instance, 145 the following examples are equivalent: 147 # Multiple Prefer Header Fields 148 POST /foo HTTP/1.1 149 Host: example.org 150 Prefer: return-accepted 151 Prefer: wait=100 153 # Single Prefer Header Field 154 POST /foo HTTP/1.1 155 Host: example.org 156 Prefer: return-accepted, wait=100 158 2.1. Cache Considerations 160 Note that while the Prefer header field is not intended to be used as 161 content negotiation mechanism, the application of a preference could 162 affect the caching characteristics of a response. Specifically, if a 163 server supports the optional application of a preference that could 164 even potentially result in a variance to a cache's handling of a 165 response entity, a Vary header field MUST be included with the 166 response listing the Prefer header field regardless of whether the 167 client actually uses Prefer in the request. 169 Because of the inherent complexities involved with properly 170 implementing server-driven content negotiation, effective caching, 171 and the application of optional preferences, implementors must 172 exercise caution when utilizing preferences in such a way as to 173 impact the caching of a response. 175 2.2. Examples 177 The following examples illustrate the use of various Preferences 178 defined by this specification, as well as undefined extensions for 179 strictly illustrative purposes: 181 # Return a 202 Accepted response for asynchronous processing 182 # if the response cannot be processed within 10 seconds. 183 # An undefined "priority" preference is also specified. 185 Prefer: return-accepted, wait=10; 186 Prefer: priority=5; 188 # Use lenient processing 190 Prefer: Lenient 192 # Use of an optional, undefined parameter on the 193 # return-minimal preference requesting a response 194 # status code of 204 for a successful response. 196 Prefer: return-minimal; status=204 198 3. The "return-accepted" Preference 200 The "return-accepted" preference indicates that the client prefers 201 the server to respond with a 202 Accepted status in the case where 202 the length of time it takes to generate a response will exceed some 203 arbitrary threshold established by the server. 205 return-accepted = "return-accepted" 207 The key motivation for the "return-accepted" preference is to 208 facilitate the operation of asynchronous request handling by allowing 209 the client to indicate to a server it's capability and preference for 210 handling 202 Accepted responses. 212 4. The "return-representation" Preference 214 The "return-representation" preference indicates that the client 215 prefers that the server include an entity representing the current 216 state of the resource in the response to a successful request. 218 return-representation = "return-representation" 220 When honoring the "return-representation" preference, the server MUST 221 include a Content-Location header field specifying the URI of the 222 resource representation being returned. Per section 6.1 of 223 [I-D.ietf-httpbis-p2-semantics], the presence of the Content-Location 224 header field in the response asserts that the payload is a 225 representation of the resource identified by the Content-Location 226 URI. 228 The "return-representation" preference is intended primarily to 229 provide a means of optimizing communication between the client and 230 server by eliminating the need for a subsequent GET request to 231 retrieve the current representation of the resource following a 232 modification. 234 Currently, after successfully processing a modification request such 235 as a POST or PUT, a server may choose to return either an entity 236 describing the status of the operation or a representation of the 237 modified resource itself. While the selection of which type of 238 entity to return, if any at all, is solely at the discretion of the 239 server, the "return-representation" preference -- along with the 240 "return-minimal" preference defined below -- allow the server to take 241 the client's preferences into consideration while constructing the 242 response. 244 5. The "return-minimal" Preference 246 The "return-minimal" preference indicates that the client wishes the 247 server to return a minimal response to a successful request. 248 Typically, such responses would utilize the 204 No Content status, 249 but other codes MAY be used as appropriate, such as a 200 status with 250 a zero-length response entity. The determination of what constitutes 251 an appropriate minimal response is solely at the discretion of the 252 server. 254 return-minimal = "return-minimal" 256 The "return-minimal" preference is intended to provide a means of 257 optimizing communication between the client and server by reducing 258 the amount of data the server is required to return to the client 259 following a request. This can be particularly useful, for instance, 260 when communicating with limited-bandwidth mobile devices or when the 261 client simply does not require any further information about the 262 result of a request beyond knowing if it was successfully processed. 264 6. The "wait" Preference 266 The "wait" preference can be used to establish an upper bound on the 267 length of time, in seconds, the client is willing to wait for a 268 response, after which the client may choose to abandon the request. 269 In the case generating a response will take longer than the time 270 specified, the server, or proxy, can choose to either return a 202 271 Accepted response, cancel processing, or continue attempting to 272 complete the request. 274 wait = "wait" BWS "=" BWS delta-seconds 276 Clients specifying the "wait" Preference SHOULD also use the Date 277 header field, as specified in [I-D.ietf-httpbis-p2-semantics] Section 278 9.2, within the request to establish the time at which the client 279 began waiting for the completion of the request. Failing to include 280 a Date header field in the request would require the server to use 281 the instant it received and began processing the request as the 282 baseline for determining how long the client has been waiting which 283 could yield unintended results depending on how out of synch the 284 client and server clocks are. 286 7. The "strict" and "lenient" Processing Preferences 288 The "strict" and "lenient" preferences are mutually-exclusive 289 directives indicating, at the servers discretion, how the client 290 wishes the server to handle potential error conditions that may arise 291 in the processing of a request. For instance, if the payload of a 292 request contains various minor syntactical or semantic errors, but 293 the server is still capable of comprehending and successfully 294 processing the request, a decision must be made to either reject the 295 request with an appropriate 4xx error response or to go ahead with 296 processing. The "strict" preference can be used by the client to 297 indicate that, in such conditions, it would prefer that the server 298 reject the request, while the "lenient" preference indicates that the 299 client would prefer the server to attempt to process the request. 300 The specific meaning and application of the "strict" and "lenient" 301 directives is specific to each type of resource, the request method 302 and the operation of the server. 304 handling = "strict" / "lenient" 306 8. Registered Preferences 308 Well-defined preferences can be registered for convenience and/or to 309 promote reuse by other applications. This specification establishes 310 an IANA registry of such relation types see Section Section 9.1. 312 Registered preference names MUST conform to the token rule, and MUST 313 be compared character-by-character in a case-insensitive fashion. 314 They SHOULD be appropriate to the specificity of the preference; 315 i.e., if the semantics are highly specific to a particular 316 application, the name should reflect that, so that more general names 317 are available for less specific use. 319 Registered preferences MUST NOT constrain servers, clients or any 320 intermediaries involved in the exchange and processing of a request 321 to any behavior required for successful processing. The use and 322 application of a preference within a given request MUST be optional 323 on the part of all participants. 325 9. IANA Considerations 327 The 'Prefer' header field should be added to the permanent registry 328 (see [RFC3864]). 330 Header field name: Prefer 331 Applicable Protocol: HTTP 332 Status: 333 Author/Change controller: IETF 334 Specification document: this specification 336 9.1. The Registry of Preferences 338 Preferences are registered on the advice of a Designated Expert 339 (appointed by the IESG or their delegate), with a Specification 340 Required (using terminology from [RFC5226]). 342 The requirements for registered preferences are described in 343 Section 8 345 Registration requests consist of the completed registration template 346 below, typically published in an RFC or Open Standard (in the sense 347 described by [RFC2026], Section 7). However, to allow for the 348 allocation of values prior to publication, the Designated Expert may 349 approve registration once they are satisfied that a specification 350 will be published. 352 Note that relation types can be registered by third parties, if the 353 Designated Expert determines that an unregistered relation type is 354 widely deployed and not likely to be registered in a timely manner. 356 The registration template is: 358 o Preference: (A value for the Prefer request header field that 359 conforms to the syntax rule given in Section 2) 360 o Description: 361 o Reference: 362 o Notes: [optional] 363 o Application Data: [optional] 365 Registration requests should be sent to the preferences@ietf.org 366 mailing list, marked clearly in the subject line (e.g., "NEW 367 PREFERENCE - example" to register an "example" preference). 369 Within at most 14 days of the request, the Designated Expert(s) will 370 either approve or deny the registration request, communicating this 371 decision to the review list and IANA. Denials should include an 372 explanation and, if applicable, suggestions as to how to make the 373 request successful. 375 Decisions (or lack thereof) made by the Designated Expert can be 376 first appealed to Application Area Directors (contactable using 377 app-ads@tools.ietf.org email address or directly by looking up their 378 email addresses on http://www.iesg.org/ website) and, if the 379 appellant is not satisfied with the response, to the full IESG (using 380 the iesg@iesg.org mailing list). 382 IANA should only accept registry updates from the Designated 383 Expert(s), and should direct all requests for registration to the 384 review mailing list. 386 9.1.1. Initial Registry Contents 388 The Preferences Registry's initial contents are: 390 o Preference: return-accepted 391 o Description: Indicates that the client prefers the server to 392 respond with a 202 Accepted status as described by Section 3 393 o Reference: [this specification] 395 o Preference: return-minimal 396 o Description: Indicates that the client prefers the server return a 397 minimal response to a request as described by Section 5 399 o Reference: [this specification] 401 o Preference: return-representation 402 o Description: Indicates that the client prefers the server to 403 include a representation of the current state of the resource in 404 response to a request as described by Section 4 405 o Reference: [this specification] 407 o Preference: wait 408 o Description: Indicates an upper bound to the lenght of time the 409 client is willing to wait for a response, after which the request 410 may be aborted. 411 o Reference: [this specification] 413 o Preference: strict 414 o Description: Indicates that the client wishes the server to apply 415 strict validation and error handling to the processing of a 416 request. 417 o Reference: [this specification] 419 o Preference: lenient 420 o Description: Indicates that the client wishes the server to apply 421 lenient validation and error handling to the processing of a 422 request. 423 o Reference: [this specification] 425 10. Security Considerations 427 Specific preferences requested by a client can introduce security 428 considerations and concerns beyond those discussed in HTTP/1.1 Parts 429 1 [I-D.ietf-httpbis-p1-messaging], 2 [I-D.ietf-httpbis-p2-semantics], 430 3 [I-D.ietf-httpbis-p3-payload], 4 [I-D.ietf-httpbis-p4-conditional], 431 5 [I-D.ietf-httpbis-p5-range], 6 [I-D.ietf-httpbis-p6-cache], and 7 432 [I-D.ietf-httpbis-p7-auth]. Implementors must refer to the 433 specifications and descriptions of each preference to determine the 434 security considerations relevant to each. 436 11. Normative References 438 [I-D.ietf-httpbis-p1-messaging] 439 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 440 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 441 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 442 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 443 in progress), October 2011. 445 [I-D.ietf-httpbis-p2-semantics] 446 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 447 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 448 J. Reschke, "HTTP/1.1, part 2: Message Semantics", 449 draft-ietf-httpbis-p2-semantics-17 (work in progress), 450 October 2011. 452 [I-D.ietf-httpbis-p3-payload] 453 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 454 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 455 J. Reschke, "HTTP/1.1, part 3: Message Payload and Content 456 Negotiation", draft-ietf-httpbis-p3-payload-17 (work in 457 progress), October 2011. 459 [I-D.ietf-httpbis-p4-conditional] 460 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 461 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 462 J. Reschke, "HTTP/1.1, part 4: Conditional Requests", 463 draft-ietf-httpbis-p4-conditional-17 (work in progress), 464 October 2011. 466 [I-D.ietf-httpbis-p5-range] 467 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 468 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 469 J. Reschke, "HTTP/1.1, part 5: Range Requests and Partial 470 Responses", draft-ietf-httpbis-p5-range-17 (work in 471 progress), October 2011. 473 [I-D.ietf-httpbis-p6-cache] 474 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 475 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., 476 Nottingham, M., and J. Reschke, "HTTP/1.1, part 6: 477 Caching", draft-ietf-httpbis-p6-cache-17 (work in 478 progress), October 2011. 480 [I-D.ietf-httpbis-p7-auth] 481 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 482 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 483 J. Reschke, "HTTP/1.1, part 7: Authentication", 484 draft-ietf-httpbis-p7-auth-17 (work in progress), 485 October 2011. 487 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 488 3", BCP 9, RFC 2026, October 1996. 490 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 491 Requirement Levels", BCP 14, RFC 2119, March 1997. 493 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 494 Procedures for Message Header Fields", BCP 90, RFC 3864, 495 September 2004. 497 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 498 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 499 May 2008. 501 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 502 Specifications: ABNF", STD 68, RFC 5234, January 2008. 504 Author's Address 506 James M Snell 508 Phone: 509 Email: jasnell@gmail.com 510 URI: