Prefer Header for HTTP
draft-snell-http-prefer-15
The information below is for an old version of the document.
Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 7240.
|
|
---|---|---|---|
Author | James M. Snell | ||
Last updated | 2012-10-12 | ||
RFC stream | Internet Engineering Task Force (IETF) | ||
Formats | |||
Reviews |
GENART Last Call review
(of
-14)
by Martin Thomson
Almost ready
SECDIR Last Call review
by Taylor Yu
Has issues
|
||
Additional resources | |||
Stream | WG state | (None) | |
Document shepherd | (None) | ||
IESG | IESG state | Became RFC 7240 (Proposed Standard) | |
Consensus boilerplate | Unknown | ||
Telechat date |
(None)
Needs a YES. Needs 10 more YES or NO OBJECTION positions to pass. |
||
Responsible AD | Barry Leiba | ||
IESG note | ** No value found for 'doc.notedoc.note' ** | ||
Send notices to | jasnell@gmail.com, mnot@mnot.net, draft-snell-http-prefer@tools.ietf.org |
draft-snell-http-prefer-15
Network Working Group J. Snell Internet-Draft October 12, 2012 Intended status: Standards Track Expires: April 15, 2013 Prefer Header for HTTP draft-snell-http-prefer-15 Abstract This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed 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 April 15, 2013. Copyright Notice Copyright (c) 2012 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. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Snell Expires April 15, 2013 [Page 1] Internet-Draft HTTP Prefer October 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 4 2. The Prefer Request Header Field . . . . . . . . . . . . . . . 4 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. The Preference-Applied Response Header Field . . . . . . . . . 7 4. Preference Definitions . . . . . . . . . . . . . . . . . . . . 8 4.1. The "return-asynch" Preference . . . . . . . . . . . . . . 8 4.2. The "return-representation" and "return-minimal" Preferences . . . . . . . . . . . . . . . . . . . . . . . 9 4.3. The "wait" Preference . . . . . . . . . . . . . . . . . . 11 4.4. The "strict" and "lenient" Processing Preferences . . . . 12 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 5.1. The Registry of Preferences . . . . . . . . . . . . . . . 13 5.2. Initial Registry Contents . . . . . . . . . . . . . . . . 14 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 7.1. Normative References . . . . . . . . . . . . . . . . . . . 15 7.2. Informative References . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 Snell Expires April 15, 2013 [Page 2] Internet-Draft HTTP Prefer October 2012 1. Introduction Within the course of processing an HTTP request there are typically a range of required and optional behaviors that a server or intermediary can employ. These often manifest in a variety of subtle and not-so-subtle ways within the response. For example, when using the HTTP PUT method to modify a resource -- similar to that defined for the Atom Publishing Protocol [RFC5023] -- the server is given the option of returning either a complete representation of a modified resource or a minimal response that indicates only the successful completion of the operation. The selection of which type of response to return to the client generally has no bearing on the successful processing of the request but could, for instance, have an impact on what actions the client must take after receiving the response. That is, returning a representation of the modified resource within the response can allow the client to avoid sending an additional subsequent GET request. Similarly, servers that process requests are often faced with decisions about how to process requests that may be technically invalid or incorrect but are still understandable. It might be the case that the server is able to overlook the technical errors in the request but still successfully process the request. Depending on the specific requirements of the application and the nature of the request being made, the client might or might not consider such lenient processing of its request to be appropriate. While the decision of exactly which behaviors to apply in these cases lies with the server processing the request, the server might wish to defer to the client to specify which optional behavior is preferred. Currently, HTTP offers no explicitly defined means of expressing the client's preferences regarding the optional aspects of handling of a given request. While HTTP does provide the Expect header -- which can be used to identify mandatory expectations for the processing of a request -- use of the field to communicate optional preferences is problematic: 1. The semantics of the Expect header field are such that intermediaries and servers are required to reject any request that states unrecognized or unsupported expectations. 2. While the Expect header field is end-to-end, the HTTP specification requires that the header be processed hop-by-hop. That is, every interceding intermediary that handles a request between the client and the origin server is required to process an expectation and determine whether it is capable of appropriately handling it. Snell Expires April 15, 2013 [Page 3] Internet-Draft HTTP Prefer October 2012 The rigid, must-understand semantics of the Expect header, therefore, make it a poor choice for the general expression of optional preferences that may be specific to an individual application and are therefore unknown to an intermediary or are otherwise irrelevant to the intermediaries successful handling of the request and response. Another option available to clients is to utilize Request URI query- string parameters to express preferences. Doing so, however, results in a variety of issues affecting the cacheability of responses. As an alternative, this specification defines a new HTTP request header field that can be used by clients to request that optional behaviors be applied by a server during the processing the request. Additionally, a handful of initial preference tokens for use with the new header are defined. In this document, the key words "MUST", "MUST NOT", quot;. | | found | | | | | | | | Refresh the entire | "A" sends the | | | event | latest copy of the | | | | event to "B" | | | | | | | Attendee handles the | | "B" updates to the | | request and updates the | | latest copy of the | | instance | | meeting. | +-------------------------+--------------------+--------------------+ Request from "A": BEGIN:VCALENDAR METHOD:REQUEST PRODID:-//Example/ExampleCalendarClient//EN VERSION:2.0 BEGIN:VEVENT UID:example-12345@example.com SEQUENCE:3 Daboo Standards Track [Page 115] RFC 5546 iTIP December 2009 RRULE:FREQ=WEEKLY RDATE;VALUE=PERIOD:19970819T210000Z/199700819T220000Z ORGANIZER:mailto:a@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:mailto:a@example.com ATTENDEE:mailto:b@example.com DESCRIPTION:IETF-C&S Conference Call SUMMARY:IETF Calendaring Working Group Meeting DTSTART:19970801T210000Z DTEND:19970801T220000Z RECURRENCE-ID:19970809T210000Z DTSTAMP:19970726T083000 STATUS:CONFIRMED END:VEVENT END:VCALENDAR "B" has the event with "UID" property "example-12345@example.com", but "B's" "SEQUENCE" property value is "1" and the event does not have an instance at the specified recurrence time. This means that "B" has missed at least one update and needs a new copy of the event. "B" requests the latest copy of the event with the following refresh message: BEGIN:VCALENDAR PRODID:-//Example/ExampleCalendarClient//EN METHOD:REFRESH VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com ATTENDEE:mailto:b@example.com UID:example-12345@example.com DTSTAMP:19970603T094000 END:VEVENT END:VCALENDAR 5. Application Protocol Fallbacks 5.1. Partial Implementation Applications that support this specification are not required to support the entire protocol. The following describes how methods and properties SHOULD "fallback" in applications that do not support the complete protocol. If a method or property is not addressed in this section, it may be ignored. Daboo Standards Track [Page 116] RFC 5546 iTIP December 2009 5.1.1. Event-Related Fallbacks +----------------+--------------------------------------------------+ | Method | Fallback | +----------------+--------------------------------------------------+ | PUBLISH | Required | | REQUEST | PUBLISH | | REPLY | Required | | ADD | Required if recurrences supported; otherwise, | | | reply with a REQUEST-STATUS "2.8; Success, | | | repeating event ignored. Scheduled as a single | | | component", and schedule as a single component. | | CANCEL | Required | | REFRESH | Required | | COUNTER | Reply with "Not Supported". | | DECLINECOUNTER | Required if COUNTER is implemented for VEVENTs; | | | otherwise, reply with "Not Supported". | +----------------+--------------------------------------------------+ +-----------------+-------------------------------------------------+ | iCalendar | Fallback | | Property | | +-----------------+-------------------------------------------------+ | CALSCALE | Ignore - assume GREGORIAN. | | PRODID | Ignore | | METHOD | Required as described in the Method list above. | | VERSION | Ignore | +-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+ | Event-Related | Fallback | | Components | | +-----------------+-------------------------------------------------+ | VALARM | Reply with "Not Supported". | | VTIMEZONE | Required if any DateTime value refers to a time | | | zone. | +-----------------+-------------------------------------------------+ Daboo Standards Track [Page 117] RFC 5546 iTIP December 2009 +-----------------+-------------------------------------------------+ | Component | Fallback | | Property | | +-----------------+-------------------------------------------------+ | ATTACH | Ignore | | ATTENDEE | Required if METHOD is REQUEST; otherwise, | | | ignore. | | CATEGORIES | Ignore | | CLASS | Ignore | | COMMENT | Ignore | | COMPLETED | Ignore | | CONTACT | Ignore | | CREATED | Ignore | | DESCRIPTION | Ignore | | DURATION | Required | | DTSTAMP | Required | | DTSTART | Required | | DTEND | Required | | EXDATE | Ignore | | GEO | Ignore | | LAST-MODIFIED | Ignore | | LOCATION | Required | | ORGANIZER | Required if METHOD is REQUEST; otherwise, | | | ignore. | | PRIORITY | Ignore | | RELATED-TO | Ignore | | RDATE | Ignore | | RRULE | Ignore - assume the first instance occurs on | | | the DTSTART property. If implemented, | | | VTIMEZONE MUST also be implemented. | | RECURRENCE-ID | Required if RRULE is implemented; otherwise, | | | ignore. | | REQUEST-STATUS | Required | | RESOURCES | Ignore | | SEQUENCE | Required | | STATUS | Ignore | | SUMMARY | Ignore | | TRANSP | Required if FREEBUSY is implemented; otherwise, | | | ignore. | | URL | Ignore | | UID | Required | | X- | Ignore | +-----------------+-------------------------------------------------+ Daboo Standards Track [Page 118] RFC 5546 iTIP December 2009 5.1.2. Free/Busy-Related Fallbacks +---------+---------------------------------------------------------+ | Method | Fallback | +---------+---------------------------------------------------------+ | PUBLISH | Required if freebusy lookups are supported; otherwise, | | | reply with a REQUEST-STATUS "3.14; Unsupported | | | capability". | | REQUEST | Required if freebusy lookups are supported; otherwise, | | | reply with a REQUEST-STATUS "3.14; Unsupported | | | capability". | | REPLY | Required if freebusy lookups are supported; otherwise, | | | reply with a REQUEST-STATUS "3.14; Unsupported | | | capability". | +---------+---------------------------------------------------------+ +-----------------+-------------------------------------------------+ | iCalendar | Fallback | | Property | | +-----------------+-------------------------------------------------+ | CALSCALE | Ignore - assume GREGORIAN. | | PRODID | Ignore | | METHOD | Required as described in the Method list above. | | VERSION | Ignore | +-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+ | Component | Fallback | | Property | | +-----------------+-------------------------------------------------+ | ATTENDEE | Required if METHOD is REQUEST; otherwise, | | | ignore. | | COMMENT | Ignore | | CONTACT | Ignore | | DTEND | Required | | DTSTAMP | Required | | DTSTART | Required | | DURATION | Ignore | | FREEBUSY | Required | | ORGANIZER | Required if METHOD is REQUEST; otherwise, | | | ignore. | | REQUEST-STATUS | Ignore | | UID | Required | | URL | Ignore | | X- | Ignore | +-----------------+-------------------------------------------------+ Daboo Standards Track [Page 119] RFC 5546 iTIP December 2009 5.1.3. To-Do-Related Fallbacks +----------------+--------------------------------------------------+ | Method | Fallback | +----------------+--------------------------------------------------+ | PUBLISH | Required | | REQUEST | PUBLISH | | REPLY | Required | | ADD | Required if recurrences supported; otherwise, | | | reply with a REQUEST-STATUS "2.8; Success, | | | repeating event ignored. Scheduled as a single | | | component", and schedule as a single component. | | CANCEL | Required | | REFRESH | Required | | COUNTER | Reply with "Not Supported". | | DECLINECOUNTER | Required if COUNTER for VTODOs is implemented; | | | otherwise, reply with "Not Supported". | +----------------+--------------------------------------------------+ +-----------------+-------------------------------------------------+ | iCalendar | Fallback | | Property | | +-----------------+-------------------------------------------------+ | CALSCALE | Ignore - assume GREGORIAN. | | PRODID | Ignore | | METHOD | Required as described in the Method list above. | | VERSION | Ignore | +-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+ | To-Do-Related | Fallback | | Components | | +-----------------+-------------------------------------------------+ | VALARM | Reply with "Not Supported". | | VTIMEZONE | Required if any DateTime value refers to a time | | | zone. | +-----------------+-------------------------------------------------+ Daboo Standards Track [Page 120] RFC 5546 iTIP December 2009 "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119]. 1.1. Syntax Notation This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234] and includes, by reference, the "token", "word", "OWS", "BWS" rules and the #rule extension as defined within Sections 3.2.1 and 3.2.4 of [I-D.ietf-httpbis-p1-messaging]. 2. The Prefer Request Header Field The Prefer request header field 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 field defined by Section 6.1.2 of [I-D.ietf-httpbis-p2-semantics] with the exception that servers are allowed to ignore stated preferences. ABNF: Prefer = "Prefer" ":" 1#preference preference = token [ BWS "=" BWS word ] *( OWS ";" [ OWS parameter ] ) parameter = token [ BWS "=" BWS word ] This header field is defined with an extensible syntax to allow for future values included in the Registry of Preferences (Section 5.1). A server that does not recognize or is unable to comply with particular preference tokens in the Prefer header field of a request Snell Expires April 15, 2013 [Page 4] Internet-Draft HTTP Prefer October 2012 MUST ignore those tokens and continue processing instead of signalling an error. A preference token can contain a value. Empty, or zero length values on both the preference token and within parameters are equivalent to no value being specified at all. The following, then, are equivalent: Prefer: foo; bar Prefer: foo; bar="" Prefer: foo=""; bar An optional set of parameters can be specified for any preference token. The meaning and application of such parameters is dependent on the definition of each preference token and the server's implementation thereof. Comparison of preference token names is case-insensitive while values are case-sensitive regardless of whether token or quoted-string values are used. The Prefer header field is end-to-end and SHOULD be forwarded by a proxy if the request is forwarded unless Prefer is explicitly identified as being hop-by-hop using the Connection header field defined by [I-D.ietf-httpbis-p1-messaging], Section 6.1. In various situations, a proxy might determine that it is capable of honoring a preference independently of the server to which the request has been directed. For instance, an intervening proxy might be capable of providing asynchronous handling of a request using 202 Accepted responses independently of the origin server. Such proxies can choose to honor the "return-asynch" preference on their own despite whether the origin is capable or willing to do so. Individual preference tokens MAY define their own requirements and restrictions as to whether and how intermediaries can apply the preference to a request independently of the origin server. Implementations MUST support multiple instances of the Prefer header field in a single message, as well as multiple preference tokens separated by commas in a single Prefer header field. The following examples are equivalent: Snell Expires April 15, 2013 [Page 5] Internet-Draft HTTP Prefer October 2012 Multiple Prefer Header Fields: POST /foo HTTP/1.1 Host: example.org Prefer: return-asynch Prefer: wait=100 Date: Tue, 20 Dec 2011 12:34:56 GMT Single Prefer Header Field: POST /foo HTTP/1.1 Host: example.org Prefer: wait=100, return-asynch Date: Tue, 20 Dec 2011 12:34:56 GMT To avoid possible ambiguity, individual preference tokens SHOULD NOT appear multiple times within a single request. If any preference is specified more than once, only the first instance is to be considered. All subsequent occurrences SHOULD be ignored without signaling an error or otherwise altering the processing of the request. This is the only case in which the ordering of preferences within a request is considered to be significant. Due to the inherent complexities involved with properly implementing server-driven content negotiation, effective caching, and the application of optional preferences, implementors are urged to exercise caution when using preferences in a way that impacts the caching of a response and SHOULD NOT use the Prefer header mechanism for content negotiation. If a server supports the optional application of a preference that might result in a variance to a cache's handling of a response entity, a Vary header field MUST be included with the response listing the Prefer header field regardless of whether the client actually used Prefer in the request. 2.1. Examples The following examples illustrate the use of various preferences defined by this specification, as well as undefined extensions for strictly illustrative purposes: 1. Return a "202 Accepted" response for asynchronous processing if the response cannot be processed within 10 seconds. An undefined "priority" preference is also specified: Prefer: return-asynch, wait=10; Prefer: priority=5; Snell Expires April 15, 2013 [Page 6] Internet-Draft HTTP Prefer October 2012 2. Use lenient processing: Prefer: Lenient 3. Use of an optional, undefined parameter on the return-minimal preference: Prefer: return-minimal; foo="some parameter" 3. The Preference-Applied Response Header Field The Preference-Applied response header MAY be included within a response message as an indication as to which Prefer tokens were honored by the server and applied to the processing of a request. ABNF: Preference-Applied = "Preference-Applied" ":" 1#token The syntax of the Preference-Applied header differs from that of the Prefer header in that token values and parameters are not included. Use of the Preference-Applied header is only necessary when it is not readily and obviously apparent that a server applied a given preference and such ambiguity might have an impact on the client's handling of the response. For instance, when using either the "return-representation" or "return-minimal" preferences, a client application might not be capable of reliably determining that the preference was applied simply by examining the payload of the response. In such case the Preference-Applied header field can be used. Request: PATCH /my-document HTTP/1.1 Host: example.org Content-Type: application/json-patch Prefer: return-representation [{"op": "add", "path": "/a", "value": 1}] Snell Expires April 15, 2013 [Page 7] Internet-Draft HTTP Prefer October 2012 Response: HTTP/1.1 200 OK Content-Type: application/json Preference-Applied: return-representation Content-Location: /my-document {"a": 1} 4. Preference Definitions The following subsections define an initial set of preferences. Additional preferences can be registered for convenience and/or to promote reuse by other applications. This specification establishes an IANA registry of such relation types (see Section 5.1). Registered preference names MUST conform to the token rule, and MUST be compared character-by-character in a case-insensitive fashion. They SHOULD be appropriate to the specificity of the preference; i.e., if the semantics are highly specific to a particular application, the name should reflect that, so that more general names remain available for less specific use. Registered preferences MUST NOT constrain servers, clients or any intermediaries involved in the exchange and processing of a request to any behavior required for successful processing. The use and application of a preference within a given request MUST be optional on the part of all participants. 4.1. The "return-asynch" Preference The &+------------------+------------------------------------------------+ | Component | Fallback | | Property | | +------------------+------------------------------------------------+ | ATTACH | Ignore | | ATTENDEE | Required if METHOD is REQUEST; otherwise, | | | ignore. | | CATEGORIES | Ignore | | CLASS | Ignore | | COMMENT | Ignore | | COMPLETED | Required | | CONTACT | Ignore | | CREATED | Ignore | | DESCRIPTION | Required if METHOD is REQUEST; otherwise, | | | ignore. | | DUE | Required | | DURATION | Required | | DTSTAMP | Required | | DTSTART | Required | | EXDATE | Ignore - reply with "Not Supported". | | LAST-MODIFIED | Ignore | | LOCATION | Ignore | | ORGANIZER | Required if METHOD is REQUEST; otherwise, | | | ignore. | | PERCENT-COMPLETE | Ignore | | PRIORITY | Required | | RECURRENCE-ID | Required if RRULE is implemented; otherwise, | | | ignore. | | RELATED-TO | Ignore | | REQUEST-STATUS | Ignore | | RDATE | Ignore | | RRULE | Ignore - assume the first instance occurs on | | | the DTSTART property. If implemented, | | | VTIMEZONE MUST also be implemented. | | RESOURCES | Ignore | | SEQUENCE | Required | | STATUS | Required | | SUMMARY | Ignore | | URL | Ignore | | UID | Required | | X- | Ignore | +------------------+------------------------------------------------+ Daboo Standards Track [Page 121] RFC 5546 iTIP December 2009 5.1.4. Journal-Related Fallbacks +---------+---------------------------------------------------------+ | Method | Fallback | +---------+---------------------------------------------------------+ | PUBLISH | Implementations MAY ignore the METHOD type. The | | | REQUEST-STATUS "3.14; Unsupported capability" MUST be | | | returned. | | ADD | Implementations MAY ignore the METHOD type. The | | | REQUEST-STATUS "3.14; Unsupported capability" MUST be | | | returned. | | CANCEL | Implementations MAY ignore the METHOD type. The | | | REQUEST-STATUS "3.14; Unsupported capability" MUST be | | | returned. | +---------+---------------------------------------------------------+ +-----------------+-------------------------------------------------+ | iCalendar | Fallback | | Property | | +-----------------+-------------------------------------------------+ | CALSCALE | Ignore - assume GREGORIAN. | | PRODID | Ignore | | METHOD | Required as described in the Method list above. | | VERSION | Ignore | +-----------------+-------------------------------------------------+ +-----------------+-------------------------------------------------+ | Journal-Related | Fallback | | Components | | +-----------------+-------------------------------------------------+ | VTIMEZONE | Required if any DateTime value refers to a time | | | zone. | +-----------------+-------------------------------------------------+ Daboo Standards Track [Page 122] RFC 5546 iTIP December 2009 +-----------------+-------------------------------------------------+ | Component | Fallback | | Property | | +-----------------+-------------------------------------------------+ | ATTACH | Ignore | | ATTENDEE | Ignore | | CATEGORIES | Ignore | | CLASS | Ignore | | COMMENT | Ignore | | CONTACT | Ignore | | CREATED | Ignore | | DESCRIPTION | Ignore | | DTSTAMP | Required | | DTSTART | Required | | EXDATE | Ignore | | LAST-MODIFIED | Ignore | | ORGANIZER | Ignore | | RECURRENCE-ID | Required if RRULE is implemented; otherwise, | | | ignore. | | RELATED-TO | Ignore | | RDATE | Ignore | | RRULE | Ignore - assume the first instance occurs on | | | the DTSTART property. If implemented, | | | VTIMEZONE MUST also be implemented. | | SEQUENCE | Required | | STATUS | Ignore | | SUMMARY | Required | | URL | Ignore | | UID | Required | | X- | Ignore | +-----------------+-------------------------------------------------+ 5.2. Latency Issues With a store-and-forward transport, it is possible for events to arrive out of sequence. That is, a "CANCEL" method may be received prior to receiving the associated "REQUEST" for the calendar component. This section discusses a few of these scenarios. 5.2.1. Cancellation of an Unknown Calendar Component When a "CANCEL" method is received before the original "REQUEST" method, the calendar will be unable to correlate the "UID" property of the cancellation with an existing calendar component. It is suggested that messages that cannot be correlated and that also contain non-zero sequence numbers be held and not discarded. Implementations MAY age them out if no other messages arrive with the same "UID" property value and a lower sequence number. Daboo Standards Track [Page 123] RFC 5546 iTIP December 2009 5.2.2. Unexpected Reply from an Unknown Delegate When an "Attendee" delegates an item to another CU, they MUST send a "REPLY" method to the "Organizer" using the "ATTENDEE" properties to indicate that the request was delegated and to whom. Hence, it is possible for an "Organizer" to receive a "REPLY" from a CU not listed as one of the original "Attendees". The resolution is left to the implementation, but it is expected that the calendaring software will either accept the reply or hold it until the related "REPLY" method is received from the "Delegator". If the version of the "REPLY" method is out of date, the "Organizer" SHOULD treat the message as a "REFRESH" message and update the "Delegate" with the correct version, provided that delegation to that delegate is acceptable. 5.3. Sequence Number Under some conditions, a CUA may receive requests and replies with the same "SEQUENCE" property value. The "DTSTAMP" property is utilized as a tie-breaker when two items with the same "SEQUENCE" property value are evaluated. 6. Security Considerations iTIP is an abstract transport protocol that will be bound to a real- time transport, a store-and-forward transport, and perhaps other transports. The transport protocol will be responsible for providing facilities for authentication and encryption using standard Internet mechanisms that are mutually understood between the sender and receiver. 6.1. Security Threats 6.1.1. Spoofing the Organizer In iTIP, the "Organizer" (or someone working on the "Organizer's" behalf) is the only person authorized to make changes to an existing "VEVENT", "return-asynch" preference indicates that the client prefers the server to respond asynchronously to a response. For instance, in the case when the length of time it takes to generate a response will exceed some arbitrary threshold established by the server, the server can honor the return-asynch preference by returning a "202 Accepted" response. ABNF: return-asynch = "return-asynch" The key motivation for the "return-asynch" preference is to facilitate the operation of asynchronous request handling by allowing the client to indicate to a server its capability and preference for handling asynchronous responses. Snell Expires April 15, 2013 [Page 8] Internet-Draft HTTP Prefer October 2012 An example request specifying the "return-asynch" preference: POST /collection HTTP/1.1 Host: example.org Content-Type: text/plain Prefer: return-asynch {Data} An example asynchronous response using "202 Accepted": HTTP/1.1 202 Accepted Location: http://example.org/collection/123 While the "202 Accepted" response status is defined by [I-D.ietf-httpbis-p2-semantics], little guidance is given on how and when to use the response code and the process for determining the subsequent final result of the operation is left entirely undefined. Therefore, whether and how any given server supports asynchronous responses is an implementation specific detail that is considered to be out of the scope of this specification. 4.2. The "return-representation" and "return-minimal" Preferences The "return-representation" preference 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. The "return-minimal" preference, on the other hand, indicates that the client wishes the server to return only a minimal response to a successful request. Typically, such responses would utilize the "204 No Content" status, but other codes MAY be used as appropriate, such as a "200" status with a zero-length response entity. The determination of what constitutes an appropriate minimal response is solely at the discretion of the server. ABNF: return-representation = "return-representation" return-minimal = "return-minimal" When honoring the "return-representation" preference, the returned representation might not be a representation of the effective request URI when the request is affecting another resource. In such cases, the Content-Location header can be used to identify the URI of the returned representation. The "return-representation" preference is intended to provide a means Snell Expires April 15, 2013 [Page 9] Internet-Draft HTTP Prefer October 2012 of optimizing communication between the client and server by eliminating the need for a subsequent GET request to retrieve the current representation of the resource following a modification. Currently, after successfully processing a modification request such as a POST or PUT, a server can choose to return either an entity describing the status of the operation or a representation of the modified resource itself. While the selection of which type of entity to return, if any at all, is solely at the discretion of the server, the "return-representation" preference -- along with the "return-minimal" preference defined below -- allow the server to take the client's preferences into consideration while constructing the response. An example request specifying the "return-representation" preference: PATCH /item/123 HTTP/1.1 Host: example.org Content-Type: text/patch Prefer: return-representation 1c1 < ABCDEFGHIJKLMNOPQRSTUVWXYZ --- > BCDFGHJKLMNPQRSTVWXYZ An example response containing the resource representation: HTTP/1.1 200 OK Content-Location: http://example.org/item/123 Preference-Applied: return-representation Content-Type: text/plain ETag: "d3b07384d113edec49eaa6238ad5ff00" BCDFGHJKLMNPQRSTVWXYZ In contrast, the "return-minimal" preference can reduce the amount of data the server is required to return to the client following a request. This can be particularly useful, for instance, when communicating with limited-bandwidth mobile devices or when the client simply does not require any further information about the result of a request beyond knowing if it was successfully processed. Snell Expires April 15, 2013 [Page 10] Internet-Draft HTTP Prefer October 2012 An example request specifying the "return-minimal" preference: POST /collection HTTP/1.1 Host: example.org Content-Type: text/plain Prefer: return-minimal {Data} An example minimal response: HTTP/1.1 201 Created Location: http://example.org/collection/123 The "return-minimal" and "return-representation" preferences are mutually exclusive directives. A request that contains both preferences can be treated as though neither were specified. 4.3. The "wait" Preference The "wait" preference can be used to establish an upper bound on the length of time, in seconds, the client expects it will take the server to process the request once it has been received. In the case that generating a response will take longer than the time specified, the server, or proxy, can choose to utilize an asynchronous processing model by returning -- for example -- a "202 Accepted" response. ABNF: wait = "wait" BWS "=" BWS delta-seconds It is important to consider that HTTP messages spend some time traversing the network and being processed by intermediaries. This increases the length of time that a client will wait for a response in addition to the time the server takes to process the request. A client that has strict timing requirements can estimate these factors and adjust the wait value accordingly. As with other preferences, the "wait" preference could be ignored. Clients can abandon requests that take longer than they are prepared to wait. Snell Expires April 15, 2013 [Page 11] Internet-Draft HTTP Prefer October 2012 For example, a server receiving the following request might choose to respond asynchronously if processing the request will take longer than 10 seconds: POST /collection HTTP/1.1 Host: example.org Content-Type: text/plain Prefer: return-asynch, wait=10 {Data} 4.4. The "strict" and "lenient" Processing Preferences The "strict" and "lenient" preferences are mutually-exclusive directives indicating, at the server's discretion, how the client wishes the server to handle potential error conditions that can arise in the processing of a request. For instance, if the payload of a request contains various minor syntactical or semantic errors, but the server is still capable of comprehending and successfully processing the request, a decision must be made to either reject the request with an appropriate "4xx" error response or go ahead with processing. The "strict" preference can be used to indicate that, while any particular error may be recoverable, the client would prefer that the server reject the request. The "lenient" preference, on the other hand, indicates that the client wishes the server to attempt to process the request. ABNF: handling = "strict" / "lenient" An example request specifying the "strict" preference: POST /collection HTTP/1.1 Host: example.org Content-Type: text/plain Prefer: strict 5. IANA Considerations The 'Prefer' and 'Preference-Applied' header fields should be added to the Permanent Message Header Fields registry defined in [RFC3864] (http://www.iana.org/assignments/message-headers/perm-headers.html). Header field name: Prefer Snell Expires April 15, 2013 [Page 12] Internet-Draft HTTP Prefer October 2012 Applicable Protocol: HTTP Status: Standard Author: James M Snell <jasnell@gmail.com> Change controller: IETF Specification document: this specification Header field name: Preference-Applied Applicable Protocol: HTTP Status: Standard Author: James M Snell <jasnell@gmail.com> Change controller: IETF Specification document: this specification 5.1. The Registry of Preferences IANA is asked to create a new registry, "HTTP Preferences", under the Hypertext Transfer Protocol (HTTP) Parameters group. New registrations will use the Specification Required policy [RFC5226]. The requirements for registered preferences are described in Section 4. Registration requests consist of the completed registration template below, typically published in the required specification. However, to allow for the allocation of values prior to publication, the Designated Expert can approve registration based on a separately submitted template once they are satisfied that a specification will be published. Preferences can be registered by third parties if the Designated Expert determines that an unregistered preference is widely deployed and not likely to be registered in a timely manner. The registration template is: o Preference: (A value for the Prefer request header field that conforms to the syntax rule given in Section 2) o Description: o Reference: o Notes: [optional] Registration requests should be sent to the ietf-http-wg@w3.org mailing list, marked clearly in the subject line (e.g., "NEW PREFERENCE - example" to register an "example" preference). Within at most 14 days of the request, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. Snell Expires April 15, 2013 [Page 13] Internet-Draft HTTP Prefer October 2012 5.2. Initial Registry Contents The Preferences Registry's initial contents are: o Preference: return-asynch o Description: Indicates that the client prefers the server to respond asynchronously to a request. o Reference: [this specification], Section 4.1 o Preference: return-minimal o Description: Indicates that the client prefers the server return a minimal response to a request. o Reference: [this specification], Section 4.2 o Preference: return-representation o Description: Indicates that the client prefers the server to include a representation of the current state of the resource in response to a request. o Reference: [this specification], Section 4.2 o Preference: wait o Description: Indicates an upper bound to the length of time the client expects it will take the server to process the request once it has been received. o Reference: [this specification], Section 4.3 o Preference: strict o Description: Indicates that the client wishes the server to apply strict validation and error handling to the processing of a request. o Reference: [this specification], Section 4.4 o Preference: lenient o Description: Indicates that the client wishes the server to apply lenient validation and error handling to the processing of a request. o Reference: [this specification], Section 4.4 6. Security Considerations Specific preferences requested by a client can introduce security considerations and concerns beyond those discussed within HTTP/1.1 [I-D.ietf-httpbis-p1-messaging] and it's additional associated specification documents. Implementers need to refer to the specifications and descriptions of each preference to determine the security considerations relevant to each. Snell Expires April 15, 2013 [Page 14] Internet-Draft HTTP Prefer October 2012 A server could incur greater costs in attempting to comply with a particular preference (for instance, the cost of providing a representation in a response that would not ordinarily contain one; or the commitment of resources necessary to track state for an asynchronous response). Unconditional compliance from a server could allow the use of preferences for denial of service. A server can ignore an expressed preference to avoid expending resources that it does not wish to commit. 7. References 7.1. Normative References [I-D.ietf-httpbis-p1-messaging] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", draft-ietf-httpbis-p1-messaging-21 (work in progress), October 2012. [I-D.ietf-httpbis-p2-semantics] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", draft-ietf-httpbis-p2-semantics-21 (work in progress), October 2012. [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004. [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. 7.2. Informative References [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007. Snell Expires April 15, 2013 [Page 15] Internet-Draft HTTP Prefer October 2012 Author's Address James M Snell Email: jasnell@gmail.com Snell Expires April 15, 2013 [Page 16]