Prefer

The HTTP Prefer request header is used by a client to request particular server behaviors.

Usage

The HTTP Prefer request header is included by a client when it wants the server to behave in certain ways. However, if the server is unable to accommodate one or more of the specifications then it will not cause the HTTP request to fail.

This HTTP reader is defined using an extensible syntax, thus allowing the grammar to scale in the future. The Registry of Preferences is maintained by IANA, but if a server does not recognize or support one of the preferences being requested by the client then it will ignore it.

The syntax is as follows:

Prefer: pref_1; parameter_1
Prefer: pref_2; parameter_2=””
Prefer: pref_3=””; parameter_3

The initial registry contents include the preferences: respond-async, return, wait, and handling.

The respond-async preference indicates that the client prefers the server to respond to requests asynchronously. The return preference takes value minimal or representation, which governs the verbosity of the HTTP response that the client expects to receive. The wait preference is used to specify an upper bound for the length of time the client is expecting to wait for a HTTP response. The handling preference can accept a value of strict or lenient, and it refers to the validation and error handling processes to be applied while generating the HTTP response.

Non-standard preferences can be used as long as they are understood by the server.

Example

Prefer: respond-async, wait=5
Prefer: handling=lenient
Prefer: task_priority=2

Takeaway

The HTTP Prefer request header is included by a client to request that the server follow certain behaviors when generating a HTTP response, although as a preference, HTTP requests can succeed if the preferences are ignored.

See also

Last updated: June 2, 2022