RFC 7240

Prefer Header for HTTP ✨

Okay bestie, the title block first 🎀 This is RFC 7240, written by J. Snell and dated June 2014. It's on the Standards Track, with ISSN 2070-1721. The title block doesn't list anything it obsoletes or updates.

Abstract 💌

So this spec defines an HTTP header field that a client can use to ask a server to use certain behaviors while it's processing a request. Iconic. 🦋

Status of This Memo 📜

This is an Internet Standards Track document.

It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). More on Internet Standards is in Section 2 of RFC 5741.

For the current status, any errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc7240. 🌸

Copyright Notice 🌈

Copyright (c) 2014 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) as in effect on the date of publication. Please read these carefully, because they describe your rights and restrictions for 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 they're provided without warranty as described in the Simplified BSD License. 🫶

Table of Contents 🗂️

   1. Introduction ....................................................2
      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 "respond-async" Preference .............................8
      4.2. The "return=representation" and "return=minimal"
           Preferences ................................................9
      4.3. The "wait" Preference .....................................11
      4.4. The "handling=strict" and "handling=lenient" Processing ...12
   5. IANA Considerations ............................................13
      5.1. The Registry of Preferences ...............................13
      5.2. Initial Registry Contents .................................15
   6. Security Considerations ........................................16
   7. References .....................................................16
      7.1. Normative References ......................................16
      7.2. Informative References ....................................16

1. Introduction ✨

Okay so while an HTTP request is being processed, there's usually a whole bunch of behaviors that a server or intermediary can use. They show up in the response in lots of subtle and not-so-subtle ways. 💅

Take the HTTP PUT method for changing a resource (kinda like the one defined for the Atom Publishing Protocol [RFC5023]). The server gets to pick: it can send back a complete representation of the modified resource, or just a minimal response saying the operation worked. Which one it picks usually doesn't affect whether the request succeeds, but it can change what the client has to do next. Like, if the response already includes the modified resource, the client can skip sending an extra GET request. Big brain move. 🧠✨

Servers also keep running into requests that are technically invalid or incorrect but still understandable. Sometimes the server can ignore those technical errors and still process the request successfully. Whether the client thinks that lenient processing is okay depends on the app's requirements and what the request is actually doing. 🙈

Here's the thing: the server gets the final say on exactly which behaviors to use in these cases, but the server might want to defer to the client about which optional behavior it prefers. 🎀

The problem is that HTTP doesn't have any explicit way to say what the client prefers about the optional parts of handling a request. HTTP does have the Expect header, which can identify mandatory expectations for processing a request. But using it to share optional preferences is messy:

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 means every intervening intermediary that handles a request between the client and the origin server is required to process an expectation and determine whether it's capable of handling it appropriately.

So the must-understand semantics of the Expect header make it a bad fit for optional preferences. 😭

Clients could also put preferences in Request URI query-string parameters. But anything that changes the URI can cause problems, like when caches record the altered URI. 💀

So this spec goes a different route: it defines a brand new HTTP request header field that clients can use to ask a server to apply optional behaviors while it processes the request. It also defines a handful of starter preference tokens to use with the new header. Main character energy. 👑

In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119]. 🦋

1.1. Syntax Notation 🧩

This spec uses the Augmented Backus-Naur Form (ABNF) notation from [RFC5234]. It also pulls in, by reference, the token, word, OWS, and BWS rules and the #rule extension, all defined in Sections 3.2.1 and 3.2.4 of [RFC7230]. And it includes the delta-seconds rule defined in Section 8.1.3 of [RFC7231]. 🌷

---

Part 1 is done, bestie! 🥹 Part 2 is coming up next with Section 2 and the Prefer Request Header Field, so stay tuned. 💖

2. The Prefer Request Header Field ✨

Okay so bestie, the Prefer request header is how a client says "hey, I'd really like the server to do this thing 🥺" 💖 but it's NOT a demand. It's kinda like the Expect header from Section 6.1.2 of [RFC7231] 🎀, except the server is totally allowed to just ignore the preference. Iconic behavior, ngl 💅

ABNF:

Prefer     = "Prefer" ":" 1#preference
preference = token [ BWS "=" BWS word ]
             *( OWS ";" [ OWS parameter ] )
parameter  = token [ BWS "=" BWS word ]

This header is built with an extensible syntax so future values can be added to the Registry of Preferences (Section 5.1) 🦋. Now here's the important part 👑: a server that doesn't recognize a preference token, or just can't follow it, MUST ignore that token and keep processing instead of throwing an error. No drama, no 400s, just vibes 🌸

Empty or zero-length values on both the preference token and within parameters are the same as having no value at all. So these are all equivalent examples of a "foo" preference with a single "bar" parameter 🧚

Prefer: foo; bar
Prefer: foo; bar=""
Prefer: foo=""; bar

Any preference token can have an optional set of parameters 🎀. What they mean depends on how each preference is defined and how the server implements it. The order of parameters doesn't matter at all, no cap 💅

For both preference token names and parameter names, comparison is case insensitive. Values, though, are case sensitive, whether they're token or quoted-string values 🙈

The Prefer header is end to end, so a proxy MUST forward it if the request gets forwarded, UNLESS Prefer is explicitly marked as hop by hop using the Connection header field defined by [RFC7230], Section 6.1 🔥

Sometimes a proxy can honor a preference all on its own, without asking the origin server first 🌈 For example, an in-between proxy might be able to handle a request asynchronously with 202 (Accepted) responses, even if the origin server can't. Those proxies can choose to honor the "respond-async" preference by themselves, whether or not the origin is able or willing to do it. Main character energy for proxies ✨

Individual preference tokens MAY set their own rules about whether and how intermediaries can apply the preference on their own, without the origin server 🦋

A client MAY send multiple Prefer header fields in one message, OR it MAY send a single Prefer header with multiple comma-separated preference tokens 💜 If there are multiple Prefer headers, it's the same as one Prefer header with all the tokens joined by commas. For example, these two are equivalent:

Multiple Prefer header fields defining three distinct preference tokens:

POST /foo HTTP/1.1
Host: example.org
Prefer: respond-async, wait=100
Prefer: handling=lenient
Date: Tue, 20 Dec 2011 12:34:56 GMT

A single Prefer header field defining the same three preference tokens:

POST /foo HTTP/1.1
Host: example.org
Prefer: handling=lenient, wait=100, respond-async
Date: Tue, 20 Dec 2011 12:34:56 GMT

To avoid any confusion, individual preference tokens SHOULD NOT appear more than once in a single request 🙃 If a preference shows up more than once, only the first instance counts. Any later ones SHOULD be ignored, without signaling an error or otherwise changing how the request is processed. This is the ONLY case where the order of preferences in a request matters 🍓

Server-driven content negotiation, caching, and optional preferences are all super tricky to get right together, so implementers are urged to be careful when a preference affects caching of a response 😭 Preferences SHOULD NOT be used for content negotiation 🫶 If a server supports the optional application of a preference that might change how a cache handles a response body, a Vary header field MUST be included in the response listing the Prefer header field, even if the client didn't actually use Prefer in the request. Alternatively, the server MAY include a Vary header with the special value "*" as defined by [RFC7231], Section 8.2.1. Just note that "Vary: *" makes it impossible for a proxy to cache the response 💀

Preference tokens look a lot like Expect tokens, but Prefer and Expect are totally different things, so preferences can't be used as expectations 💅✨

2.1. Examples

These examples show off some preferences defined in this spec, plus some made-up extensions just for illustration 🧚

1. Return a 202 (Accepted) response for async processing if the request can't be processed within 10 seconds. There's also an undefined "priority" preference here 🦋:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async, wait=10
Prefer: priority=5

{...}

2. Use lenient processing 🌸:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: Lenient

{...}

3. Use of an optional, undefined parameter on the return=minimal preference 🎀:

POST /some-resource HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: return=minimal; foo="some parameter"

{...}

---

3. The Preference-Applied Response Header Field 🎀

The Preference-Applied response header MAY be included in a response to say which Prefer tokens the server actually honored and applied to processing the request 💖

ABNF:

Preference-Applied = "Preference-Applied" ":" 1#applied-pref
applied-pref = token [ BWS "=" BWS word ]

The big difference from Prefer syntax is that Preference-Applied doesn't include parameters 🙈

You only need Preference-Applied when it's NOT obvious that the server applied a preference, and when that uncertainty could mess with how the client handles the response 🤔 For example, with "return=representation" or "return=minimal", a client might not be able to tell reliably just by looking at the payload whether the preference was applied. In that case, Preference-Applied can help 💅

Request:

PATCH /my-document HTTP/1.1
Host: example.org
Content-Type: application/example-patch
Prefer: return=representation

[{"op": "add", "path": "/a", "value": 1}]

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Preference-Applied: return=representation
Content-Location: /my-document

{"a": 1}

4. Preference Definitions 👑

The next subsections define a starter set of preferences 🌈 More can be registered for convenience or so other apps can reuse them ✨ This spec sets up an IANA registry of preferences (see Section 5.1) 🦋

4.1. The "respond-async" Preference 🔥

The "respond-async" preference says the client would like the server to respond asynchronously 💜 For example, if generating the response is going to take longer than some threshold the server picked, the server can honor "respond-async" by returning a 202 (Accepted) response 🧚

ABNF:

respond-async = "respond-async"

The whole point of "respond-async" is to make async handling work, by letting the client tell the server "I can handle async responses and I'd like that" 🫶

An example request asking for "respond-async":

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: respond-async

{Data}

An example async response using 202 (Accepted):

HTTP/1.1 202 Accepted
Location: http://example.org/collection/123

202 (Accepted) is defined by [RFC7231], but that spec doesn't really say how or when to use it, and how the final result gets figured out is left totally undefined 😭 So whether and how a server supports async responses is an implementation-specific detail, and it's out of scope for this specification 🌸

4.2. The "return=representation" and "return=minimal" Preferences

okay so return=representation is the client basically saying "hey bestie, after a successful request, can you send back the current state of the resource in your response? 🥺📄" 💖

return=minimal is the opposite vibe: "keep it short, just send me the bare minimum after a successful request" 🤏✨ Usually that's a 204 (No Content) status, but other codes MAY be used when they make sense, like a 200 (OK) status with a zero-length response entity. Figuring out what counts as an appropriate minimal response is totally at the server's discretion 💅

ABNF:

return = "return" BWS "=" BWS ("representation" / "minimal")

when the server honors return=representation, the returned representation might not be a representation of the effective request URI if the request is affecting a different resource 👀 in that case, the Content-Location header can be used to say which URI the returned representation belongs to 🗺️

return=representation is all about optimizing the conversation between client and server 🚀 It cuts out the need for a follow-up GET request just to fetch the current representation of the resource after a modification. Iconic efficiency 😤

after successfully processing a modification request like a POST or PUT, a server can pick between returning an entity that describes the status of the operation, or a representation of the modified resource itself 🎀 Which one it sends (or whether it sends anything at all) is 100% the server's call. But return=representation and the return=minimal preference (defined below) let the server take the client's preferences into account while building the response. It's giving collaboration 🫶

an example request specifying return=representation:

PATCH /item/123 HTTP/1.1
Host: example.org
Content-Type: application/example-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
Content-Type: text/plain
ETag: "d3b07384d113edec49eaa6238ad5ff00"

BCDFGHJKLMNPQRSTVWXYZ

meanwhile, return=minimal can shrink the amount of data the server is required to send back after a request 🪶 This is especially handy when someone is on a limited-bandwidth mobile device, or when the client just needs to know whether the request was successfully processed and doesn't care about anything else 📱💅

an example request specifying return=minimal:

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

return=minimal and return=representation are mutually exclusive directives 🙅‍♀️ It's anticipated that there will never be a situation where it makes sense for one request to include both. If a request does have both, it's most likely a coding error on the client's side 🙈 So a request containing both preferences can be treated as though neither were specified 🤷‍♀️

---

4.3. The "wait" Preference

the wait preference lets the client set an upper bound, in seconds, on how long it expects the server to take to process the request once it's been received ⏳ If generating a response is going to take longer than that time, the server, or a proxy, can choose to switch to an asynchronous processing model, for example by returning a 202 (Accepted) response 🧚

ABNF:

wait = "wait" BWS "=" BWS delta-seconds

this part is important 📬 HTTP messages spend some time traveling across the network and getting processed by intermediaries. That adds to how long a client waits for a response, on top of the time the server spends processing the request. A client with strict timing needs can estimate these factors and adjust the wait value to match 🎯

as with other preferences, the wait preference could be ignored 🫠 Clients can abandon requests that take longer than they're prepared to wait 🏃‍♀️

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: respond-async, wait=10

{Data}

---

4.4. The "handling=strict" and "handling=lenient" Processing Preferences

the handling=strict and handling=lenient preferences tell the server, at its discretion, how the client wants it to handle potential error conditions that can pop up while processing a request 🧐 For instance, say the payload of a request has a few minor syntactical or semantic errors, but the server can still understand and successfully process it. Then the server has to decide: reject the request with an appropriate "4xx" error response, or just go ahead and process it 🤔 handling=strict says that, even if a particular error could be recovered from, the client would rather the server reject the request 🚫 handling=lenient, on the other hand, says the client wants the server to try to process the request anyway 💖

ABNF:

handling = "handling" BWS "=" BWS ("strict" / "lenient")

an example request specifying the strict preference:

POST /collection HTTP/1.1
Host: example.org
Content-Type: text/plain
Prefer: handling=strict

handling=strict and handling=lenient are mutually exclusive directives too 🙃 It's anticipated that there will never be a situation where it makes sense for one request to include both. Any request that does is most likely the result of a coding error on the client's side 😭 So a request containing both preferences can be treated as though neither were specified 🫶

---

5. IANA Considerations

the Prefer and Preference-Applied header fields have been added to the "Permanent Message Header Field Names" registry defined in [RFC3864] (http://www.iana.org/assignments/message-headers) 📋✨

Header field name: Prefer

Applicable Protocol: HTTP

Status: Standard

Author: James M Snell <jasnell@gmail.com>

Change controller: IETF

Specification document: this specification, Section 2

Header field name: Preference-Applied

Applicable Protocol: HTTP

Status: Standard

Author: James M Snell <jasnell@gmail.com>

Change controller: IETF

Specification document: this specification, Section 3

---

5.1. The Registry of Preferences

IANA has created a new registry, "HTTP Preferences", under the "Hypertext Transfer Protocol (HTTP) Parameters" registry 🗂️ New registrations will use the Specification Required policy [RFC5226]. The requirements for registered preferences are described in Section 4 💅

registration requests usually consist of the completed registration template below, typically published in the required specification. But to allow values to be allocated before publication, the Designated Expert can approve a registration based on a separately submitted template, once they're satisfied that a specification will be published 🎀 Preferences can also 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:

• Preference: (A value for the Prefer request header field that conforms to the syntax rule given in Section 2)
• Value: (An enumeration or description of possible values for the preference token).
• Optional Parameters: (An enumeration of optional parameters, and their values, associated with the preference token).
• Description:
• Reference:
• Notes: [optional]

the "Value" and "Optional Parameters" fields MAY be omitted from the registration template if the specific preference token definition does not define either 🫧

registration requests should be sent to the <ietf-http-wg@w3.org> mailing list, clearly marked in the subject line (for example, "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 that decision to the review list and IANA ⏰ Denials should include an explanation and, if applicable, suggestions for how to make the request successful 💡

the Expert Reviewer shall ensure:

• That the requested preference name conforms to the token rule in Section 2 and that it is not identical to any other registered preference name;
• That any associated value, parameter names, and values conform to the relevant ABNF grammar specifications in Section 2;
• That the name is 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 uses. 🧁
• That requested preferences do not constrain servers, clients, or any intermediaries to any behavior required for successful processing; and
• That the specification document defining the preference includes a proper and complete discussion of any security considerations relevant to the use of the preference. 🔐

---

5.2. Initial Registry Contents

the "HTTP Preferences" registry's initial contents are:

• Preference: respond-async
  • Description: Indicates that the client prefers that the server respond asynchronously to a request.
  • Reference: [this specification], Section 4.1
• Preference: return
  • Value: One of either "minimal" or "representation"
  • Description: When the value is "minimal", it indicates that the client prefers that the server return a minimal response to a request. When the value is "representation", it indicates that the client prefers that the server include a representation of the current state of the resource in response to a request.
  • Reference: [this specification], Section 4.2
• Preference: wait
  • Description: Indicates an upper bound to the length of time the client expects it will take for the server to process the request once it has been received.
  • Reference: [this specification], Section 4.3
• Preference: handling
  • Value: One of either "strict" or "lenient"
  • Description: When value is "strict", it indicates that the client wishes the server to apply strict validation and error handling to the processing of a request. When the value is "lenient", it indicates that the client wishes the server to apply lenient validation and error handling to the processing of the request.
  • Reference: [this specification], Section 4.4

6. Security Considerations 🔐✨

okay bestie, this section is lowkey the most important one for keeping our servers safe, so pay attention 👀💅

Specific preferences a client asks for can bring in security considerations and concerns that go beyond what's covered in HTTP/1.1 [RFC7230] and its related specs (check [RFC7230] for the full list of associated works) 🎀. Implementers need to look at the specifications and descriptions of each preference to figure out which security considerations apply to each one 🧐💖.

A server could end up paying more to try to follow a certain preference 💸. For example, it might cost extra to send back a representation in a response that wouldn't normally have one, or it might need to commit resources to keep track of state for an asynchronous response 🌀. If a server has to comply with every preference no matter what, then preferences could be abused for denial of service 🚨😭. A server is allowed to ignore a preference it's been sent if it doesn't want to spend resources on it 🙈✨. That's the escape hatch, periodt 💅.

7. References 📚🦋

7.1. Normative References 💜

• [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.
• [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2014.
• [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014.

7.2. Informative References 🌈

• [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing Protocol", RFC 5023, October 2007.

---

Author's Address 🖋️💖

James M Snell

EMail: jasnell@gmail.com