Prefer Header for HTTP

Preference token names and parameter names are case-insensitive, while values are case-sensitive. Empty or zero-length values on preference tokens and parameters are equivalent to no value being specified, so `foo; bar`, `foo; bar=""`, and `foo=""; bar` are all equivalent.

http

The Expect header was rejected as a mechanism for optional preferences because intermediaries and servers are required to reject requests with unrecognized expectations, and every intermediary must process expectations hop-by-hop — semantics incompatible with optional, ignorable preferences.

http

The Preference-Applied header is only necessary when it is not readily apparent whether a preference was applied, and such ambiguity might impact the client's handling of the response — for example, with return=representation/minimal where examining the payload alone may not reveal whether the preference was honored.

http

The "respond-async" preference was introduced to facilitate asynchronous request handling by signaling the client's capability and willingness to handle 202 responses, since RFC 7231 defines 202 but provides little guidance on when to use it or how to retrieve the eventual result.

http

Using URI query-string parameters to express preferences was rejected because altering the URI has undesirable effects, such as caches recording the altered URI as distinct from the original.

http

A client MAY send multiple Prefer header fields or a single field with comma-separated tokens; both forms are equivalent. Multiple Prefer fields are treated as a single field formed by comma-separated concatenation of all tokens.

http

The "handling=strict" and "handling=lenient" preferences are mutually exclusive directives. A request containing both can be treated as though neither were specified.

http

The "return=minimal" and "return=representation" preferences are mutually exclusive directives. A request containing both can be treated as though neither were specified, as including both is likely the result of a coding error.

http

A server that does not recognize or is unable to comply with particular preference tokens in the Prefer header MUST ignore those tokens and continue processing instead of signaling an error.

http

If a server supports an optional preference that might result in a variance to a cache's handling of a response, a Vary header MUST be included listing the Prefer header field, regardless of whether the client actually used Prefer in the request.

http

Implementations SHOULD NOT use the Prefer header mechanism for content negotiation, due to complexities with server-driven content negotiation and effective caching.

http

Individual preference tokens SHOULD NOT appear multiple times within a single request. If a preference appears more than once, only the first instance is considered; all subsequent occurrences SHOULD be ignored without signaling an error.

http

The Prefer header field is end-to-end and MUST be forwarded by a proxy if the request is forwarded, unless Prefer is explicitly identified as hop-by-hop using the Connection header field.

http

The "handling=strict" preference indicates the client prefers the server to apply strict validation and reject requests with minor errors. The "handling=lenient" preference indicates the client wishes the server to attempt processing despite minor errors. ABNF: `handling = "handling" BWS "=" BWS ("strict" / "lenient")`.

http

The Prefer request header field allows clients to indicate that particular server behaviors are preferred but not required for successful completion of the request. Servers are allowed to ignore stated preferences, distinguishing it from the Expect header.

http

The Preference-Applied response header MAY be included in a response to indicate which Prefer tokens were honored by the server. Its ABNF is `Preference-Applied = "Preference-Applied" ":" 1#applied-pref` where `applied-pref = token [ BWS "=" BWS word ]`; parameters are not included.

http

The "respond-async" preference indicates the client prefers the server to respond asynchronously. The server can honor it by returning a 202 (Accepted) response when generating a timely response would exceed some threshold. ABNF: `respond-async = "respond-async"`.

http

The "return=minimal" preference requests that the server return only a minimal response to a successful request, typically using 204 (No Content) or a 200 with zero-length entity. The determination of what constitutes minimal is at the server's discretion. ABNF: `return = "return" BWS "=" BWS ("representation" / "minimal")`.

http

The "return=representation" preference requests that the server include an entity representing the current state of the resource in the response, enabling the client to avoid a subsequent GET request after a modification.

http

The "wait" preference establishes an upper bound in seconds on the time the client expects it will take the server to process the request. If processing will exceed this time, the server or proxy may return a 202 (Accepted) response. ABNF: `wait = "wait" BWS "=" BWS delta-seconds`.

http

IANA has created a new "HTTP Preferences" registry under the "Hypertext Transfer Protocol (HTTP) Parameters" registry, using the Specification Required policy. Initial entries are: respond-async, return (values: minimal/representation), wait, and handling (values: strict/lenient).

http, registry

The Prefer and Preference-Applied header field names have been added to the IANA "Permanent Message Header Field Names" registry defined in RFC 3864, with applicable protocol HTTP and status Standard.

http, registry

A server could incur greater costs complying with certain preferences (e.g., providing a full representation, or tracking state for async responses). Unconditional compliance could allow preferences to be exploited for denial of service; servers may ignore preferences to avoid committing unwanted resources.

http, security

Specific preferences requested by a client can introduce security considerations beyond those in HTTP/1.1. Implementers must refer to the specifications of each preference to determine relevant security concerns.

http, security

The Prefer header uses the ABNF: `Prefer = "Prefer" ":" 1#preference`, where `preference = token [ BWS "=" BWS word ] *( OWS ";" [ OWS parameter ] )` and `parameter = token [ BWS "=" BWS word ]`. Token and parameter names are case-insensitive; values are case-sensitive.

http