idnits 2.17.1 draft-snell-http-prefer-10.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 19, 2011) is 4505 days in the past. Is this intentional? 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 (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Snell 3 Internet-Draft December 19, 2011 4 Intended status: Informational 5 Expires: June 21, 2012 7 Prefer Header for HTTP 8 draft-snell-http-prefer-10 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 21, 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. Content Negotiation and Cache Considerations . . . . . . . 5 54 2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 3. The "return-asynch" Preference . . . . . . . . . . . . . . . . 5 56 4. The "return-representation" Preference . . . . . . . . . . . . 6 57 5. The "return-minimal" Preference . . . . . . . . . . . . . . . 7 58 6. The "wait" Preference . . . . . . . . . . . . . . . . . . . . 8 59 7. The "strict" and "lenient" Processing Preferences . . . . . . 9 60 8. Registered Preferences . . . . . . . . . . . . . . . . . . . . 10 61 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 62 9.1. The Registry of Preferences . . . . . . . . . . . . . . . 10 63 9.1.1. Initial Registry Contents . . . . . . . . . . . . . . 11 64 10. Security Considerations . . . . . . . . . . . . . . . . . . . 12 65 11. Normative References . . . . . . . . . . . . . . . . . . . . . 13 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 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 Section 1.2 [I-D.ietf-httpbis-p1-messaging]. 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 Section 9.3 of 91 [I-D.ietf-httpbis-p2-semantics] with the exception that servers are 92 allowed to ignore 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-asynch" 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 Section 3.2 of [I-D.ietf-httpbis-p1-messaging], 142 Implementations MUST be capable of supporting either multiple 143 instances of the Prefer header field in a single message as well as 144 multiple preference tokens separated by commas in a single Prefer 145 header, for instance, the following examples are equivalent: 147 Multiple Prefer Header Fields: 149 POST /foo HTTP/1.1 150 Host: example.org 151 Prefer: return-asynch 152 Prefer: wait=100 153 Date: Tue, 20 Dec 2011 12:34:56 GMT 155 Single Prefer Header Field: 157 POST /foo HTTP/1.1 158 Host: example.org 159 Prefer: return-asynch, wait=100 160 Date: Tue, 20 Dec 2011 12:34:56 GMT 162 2.1. Content Negotiation and Cache Considerations 164 Note that while the Prefer header field is not intended to be used as 165 content negotiation mechanism, the application of a preference 166 potentially could affect the caching characteristics of a response. 167 Specifically, if a server supports the optional application of a 168 preference that could even potentially result in a variance to a 169 cache's handling of a response entity, a Vary header field MUST be 170 included with the response listing the Prefer header field regardless 171 of whether the client actually uses Prefer in the request. 173 Because of the inherent complexities involved with properly 174 implementing server-driven content negotiation, effective caching, 175 and the application of optional preferences, implementors must 176 exercise caution when utilizing preferences in such a way as to 177 impact the caching of a response and SHOULD avoid using the Prefer 178 header mechanism for content negotiation. 180 2.2. Examples 182 The following examples illustrate the use of various Preferences 183 defined by this specification, as well as undefined extensions for 184 strictly illustrative purposes: 186 Return a 202 Accepted response for asynchronous processing if the 187 response cannot be processed within 10 seconds. An undefined 188 "priority" preference is also specified. 190 Prefer: return-asynch, wait=10; 191 Prefer: priority=5; 193 Use lenient processing 195 Prefer: Lenient 197 Use of an optional, undefined parameter on the return-minimal 198 preference requesting a response status code of 204 for a successful 199 response. 201 Prefer: return-minimal; status=204 203 3. The "return-asynch" Preference 205 The "return-asynch" preference indicates that the client prefers the 206 server to respond asynchronously to a response. For instance, in the 207 case when the length of time it takes to generate a response will 208 exceed some arbitrary threshold established by the server, the server 209 may honor the return-asynch preference by returning either a 202 210 Accepted or 303 See Other response. 212 return-asynch = "return-asynch" 214 The key motivation for the "return-asynch" preference is to 215 facilitate the operation of asynchronous request handling by allowing 216 the client to indicate to a server it's capability and preference for 217 handling asynchronous responses. 219 An example request specifying the "return-asynch" preference: 221 POST /collection HTTP/1.1 222 Host: example.org 223 Content-Type: text/plain 224 Prefer: return-asynch 226 {Data} 228 An example asynchronous response using 202 Accepted: 230 HTTP/1.1 202 Accepted 231 Location: http://example.org/collection/123 233 An alternative asynchronous response using 303 See Other: 235 HTTP/1.1 303 See Other 236 Location: http://example.org/collection/123 237 Retry-After: 10 239 4. The "return-representation" Preference 241 The "return-representation" preference indicates that the client 242 prefers that the server include an entity representing the current 243 state of the resource in the response to a successful request. 245 return-representation = "return-representation" 247 When honoring the "return-representation" preference, the server MUST 248 include a Content-Location header field specifying the URI of the 249 resource representation being returned. Per section 6.1 of 250 [I-D.ietf-httpbis-p2-semantics], the presence of the Content-Location 251 header field in the response asserts that the payload is a 252 representation of the resource identified by the Content-Location 253 URI. 255 The "return-representation" preference is intended primarily to 256 provide a means of optimizing communication between the client and 257 server by eliminating the need for a subsequent GET request to 258 retrieve the current representation of the resource following a 259 modification. 261 Currently, after successfully processing a modification request such 262 as a POST or PUT, a server may choose to return either an entity 263 describing the status of the operation or a representation of the 264 modified resource itself. While the selection of which type of 265 entity to return, if any at all, is solely at the discretion of the 266 server, the "return-representation" preference -- along with the 267 "return-minimal" preference defined below -- allow the server to take 268 the client's preferences into consideration while constructing the 269 response. 271 An example request specifying the "return-representation" preference: 273 PUT /collection/123 HTTP/1.1 274 Host: example.org 275 Content-Type: text/plain 276 Prefer: return-representation 278 {Data} 280 An example response containing the resource representation: 282 HTTP/1.1 200 OK 283 Content-Location: http://example.org/collection/123 284 Content-Type: text/plain 286 {Data} 288 5. The "return-minimal" Preference 290 The "return-minimal" preference indicates that the client wishes the 291 server to return a minimal response to a successful request. 292 Typically, such responses would utilize the 204 No Content status, 293 but other codes MAY be used as appropriate, such as a 200 status with 294 a zero-length response entity. The determination of what constitutes 295 an appropriate minimal response is solely at the discretion of the 296 server. 298 return-minimal = "return-minimal" 300 The "return-minimal" preference is intended to provide a means of 301 optimizing communication between the client and server by reducing 302 the amount of data the server is required to return to the client 303 following a request. This can be particularly useful, for instance, 304 when communicating with limited-bandwidth mobile devices or when the 305 client simply does not require any further information about the 306 result of a request beyond knowing if it was successfully processed. 308 An example request specifying the "return-minimal" preference: 310 POST /collection HTTP/1.1 311 Host: example.org 312 Content-Type: text/plain 313 Prefer: return-minimal 315 {Data} 317 An example response containing the resource representation: 319 HTTP/1.1 201 Created 320 Location: http://example.org/collection/123 321 Content-Length: 0 323 6. The "wait" Preference 325 The "wait" preference can be used to establish an upper bound on the 326 length of time, in seconds, the client is willing to wait for a 327 response, after which the client may choose to abandon the request. 328 In the case generating a response will take longer than the time 329 specified, the server, or proxy, MAY choose to utilize an 330 asynchronous processing model by returning, for example, 202 Accepted 331 or 303 See Other responses. 333 wait = "wait" BWS "=" BWS delta-seconds 335 Clients specifying the "wait" Preference SHOULD also use the Date 336 header field, as specified in Section 9.2 of 337 [I-D.ietf-httpbis-p2-semantics], within the request to establish the 338 time at which the client began waiting for the completion of the 339 request. Failing to include a Date header field in the request would 340 require the server to use the instant it received or began processing 341 the request as the baseline for determining how long the client has 342 been waiting which could yield unintended results. 344 The lack of a Date header in the request, or poor clock 345 synchronization between the client and server makes it impossible to 346 determine the exact length of time the client has already been 347 waiting when the request is received by the server. The only 348 reliable information conveyed by the wait preference is that the 349 client is not expecting the server to spend more than the specified 350 time on request processing and may terminate the transaction at any 351 time. 353 An example request specifying the "wait" and "return-asynch" 354 preferences to indicate that the client wishes the server to respond 355 asynchronously if processing of the request will take longer than 10 356 seconds: 358 POST /collection HTTP/1.1 359 Host: example.org 360 Content-Type: text/plain 361 Prefer: return-asynch, wait=10 362 Date: Tue, 20 Dec 2011 12:34:56 GMT 364 {Data} 366 7. The "strict" and "lenient" Processing Preferences 368 The "strict" and "lenient" preferences are mutually-exclusive 369 directives indicating, at the servers discretion, how the client 370 wishes the server to handle potential error conditions that may arise 371 in the processing of a request. For instance, if the payload of a 372 request contains various minor syntactical or semantic errors, but 373 the server is still capable of comprehending and successfully 374 processing the request, a decision must be made to either reject the 375 request with an appropriate 4xx error response or to go ahead with 376 processing. The "strict" preference can be used by the client to 377 indicate that, in such conditions, it would prefer that the server 378 reject the request, while the "lenient" preference indicates that the 379 client would prefer the server to attempt to process the request. 380 The specific meaning and application of the "strict" and "lenient" 381 directives is specific to each type of resource, the request method 382 and the operation of the server. 384 handling = "strict" / "lenient" 386 An example request specifying the "strict" preference: 388 POST /collection HTTP/1.1 389 Host: example.org 390 Content-Type: text/plain 391 Prefer: strict 393 An example request specifying the "lenient" preference: 395 POST /collection HTTP/1.1 396 Host: example.org 397 Content-Type: text/plain 398 Prefer: lenient 400 8. Registered Preferences 402 Well-defined preferences can be registered for convenience and/or to 403 promote reuse by other applications. This specification establishes 404 an IANA registry of such relation types see Section 9.1. 406 Registered preference names MUST conform to the token rule, and MUST 407 be compared character-by-character in a case-insensitive fashion. 408 They SHOULD be appropriate to the specificity of the preference; 409 i.e., if the semantics are highly specific to a particular 410 application, the name should reflect that, so that more general names 411 are available for less specific use. 413 Registered preferences MUST NOT constrain servers, clients or any 414 intermediaries involved in the exchange and processing of a request 415 to any behavior required for successful processing. The use and 416 application of a preference within a given request MUST be optional 417 on the part of all participants. 419 9. IANA Considerations 421 The 'Prefer' header field should be added to the permanent registry 422 (see [RFC3864]). 424 Header field name: Prefer 425 Applicable Protocol: HTTP 426 Status: 427 Author: James M Snell 428 Change controller: IETF 429 Specification document: this specification 431 9.1. The Registry of Preferences 433 Preferences are registered on the advice of a Designated Expert 434 (appointed by the IESG or their delegate), with a Specification 435 Required (using terminology from [RFC5226]). 437 The requirements for registered preferences are described in 438 Section 8. 440 Registration requests consist of the completed registration template 441 below, typically published in an RFC or Open Standard (in the sense 442 described by Section 7 of [RFC2026]). However, to allow for the 443 allocation of values prior to publication, the Designated Expert may 444 approve registration once they are satisfied that a specification 445 will be published. 447 Note that relation types can be registered by third parties, if the 448 Designated Expert determines that an unregistered relation type is 449 widely deployed and not likely to be registered in a timely manner. 451 The registration template is: 453 o Preference: (A value for the Prefer request header field that 454 conforms to the syntax rule given in Section 2) 455 o Description: 456 o Reference: 457 o Notes: [optional] 458 o Application Data: [optional] 460 Registration requests should be sent to the preferences@ietf.org 461 mailing list, marked clearly in the subject line (e.g., "NEW 462 PREFERENCE - example" to register an "example" preference). 464 Within at most 14 days of the request, the Designated Expert(s) will 465 either approve or deny the registration request, communicating this 466 decision to the review list and IANA. Denials should include an 467 explanation and, if applicable, suggestions as to how to make the 468 request successful. 470 Decisions (or lack thereof) made by the Designated Expert can be 471 first appealed to Application Area Directors (contactable using 472 app-ads@tools.ietf.org email address or directly by looking up their 473 email addresses on http://www.iesg.org/ website) and, if the 474 appellant is not satisfied with the response, to the full IESG (using 475 the iesg@iesg.org mailing list). 477 IANA should only accept registry updates from the Designated 478 Expert(s), and should direct all requests for registration to the 479 review mailing list. 481 9.1.1. Initial Registry Contents 483 The Preferences Registry's initial contents are: 485 o Preference: return-asynch 486 o Description: Indicates that the client prefers the server to 487 respond asynchronously to a request as described by Section 3 488 o Reference: [this specification] 490 o Preference: return-minimal 491 o Description: Indicates that the client prefers the server return a 492 minimal response to a request as described by Section 5 493 o Reference: [this specification] 495 o Preference: return-representation 496 o Description: Indicates that the client prefers the server to 497 include a representation of the current state of the resource in 498 response to a request as described by Section 4 499 o Reference: [this specification] 501 o Preference: wait 502 o Description: Indicates an upper bound to the lenght of time the 503 client is willing to wait for a response, after which the request 504 may be aborted. 505 o Reference: [this specification] 507 o Preference: strict 508 o Description: Indicates that the client wishes the server to apply 509 strict validation and error handling to the processing of a 510 request. 511 o Reference: [this specification] 513 o Preference: lenient 514 o Description: Indicates that the client wishes the server to apply 515 lenient validation and error handling to the processing of a 516 request. 517 o Reference: [this specification] 519 10. Security Considerations 521 Specific preferences requested by a client can introduce security 522 considerations and concerns beyond those discussed in HTTP/1.1 Parts 523 1 [I-D.ietf-httpbis-p1-messaging], 2 [I-D.ietf-httpbis-p2-semantics], 524 3 [I-D.ietf-httpbis-p3-payload], 4 [I-D.ietf-httpbis-p4-conditional], 525 5 [I-D.ietf-httpbis-p5-range], 6 [I-D.ietf-httpbis-p6-cache], and 7 526 [I-D.ietf-httpbis-p7-auth]. Implementors must refer to the 527 specifications and descriptions of each preference to determine the 528 security considerations relevant to each. 530 11. Normative References 532 [I-D.ietf-httpbis-p1-messaging] 533 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 534 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 535 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 536 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 537 in progress), October 2011. 539 [I-D.ietf-httpbis-p2-semantics] 540 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 541 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 542 J. Reschke, "HTTP/1.1, part 2: Message Semantics", 543 draft-ietf-httpbis-p2-semantics-17 (work in progress), 544 October 2011. 546 [I-D.ietf-httpbis-p3-payload] 547 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 548 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 549 J. Reschke, "HTTP/1.1, part 3: Message Payload and Content 550 Negotiation", draft-ietf-httpbis-p3-payload-17 (work in 551 progress), October 2011. 553 [I-D.ietf-httpbis-p4-conditional] 554 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 555 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 556 J. Reschke, "HTTP/1.1, part 4: Conditional Requests", 557 draft-ietf-httpbis-p4-conditional-17 (work in progress), 558 October 2011. 560 [I-D.ietf-httpbis-p5-range] 561 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 562 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 563 J. Reschke, "HTTP/1.1, part 5: Range Requests and Partial 564 Responses", draft-ietf-httpbis-p5-range-17 (work in 565 progress), October 2011. 567 [I-D.ietf-httpbis-p6-cache] 568 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 569 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., 570 Nottingham, M., and J. Reschke, "HTTP/1.1, part 6: 571 Caching", draft-ietf-httpbis-p6-cache-17 (work in 572 progress), October 2011. 574 [I-D.ietf-httpbis-p7-auth] 575 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 576 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 577 J. Reschke, "HTTP/1.1, part 7: Authentication", 578 draft-ietf-httpbis-p7-auth-17 (work in progress), 579 October 2011. 581 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 582 3", BCP 9, RFC 2026, October 1996. 584 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 585 Requirement Levels", BCP 14, RFC 2119, March 1997. 587 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 588 Procedures for Message Header Fields", BCP 90, RFC 3864, 589 September 2004. 591 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 592 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 593 May 2008. 595 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 596 Specifications: ABNF", STD 68, RFC 5234, January 2008. 598 Author's Address 600 James M Snell 602 Email: jasnell@gmail.com