The HTTPPrefer header allows clients to indicate preferences for specific server behaviors during request processing.

Syntax

Prefer: <preference>

Directives

respond-async

The client prefers asynchronous processing.For example, the server might respond with202 Accepted response indicated that the request has been accepted, along with theLocation header that has a URL that the client can use to monitor the state of the processing.

return=minimal

Requests that the server return minimal content (a headers-only response).

return=representation

Requests a full resource representation in the response.

wait=<seconds>

The time within which the client expects the server to provide a response, from the point at which the request was received.If therespond-async preference is also provided, the server should respond asynchronously if processing the request will exceed the wait time.Otherwise, the server should consider that the client will timeout after thewait time (response behavior depends on server implementation).

handling=lenient

The client wishes the server to apply lenient validation and error handling to the processing of the request.

handling=strict

The client wishes the server to apply strict validation and error handling to the processing of the request.

Custom preference

Vendors or applications may define their own preferences to suit specific needs.For example,Prefer: timezone=America/Los_Angeles.

Examples

Requesting minimal response

The following request asks for a minimal response.This is typically a headers-only response (as opposed toreturn=representation where a representation is included in the response body):

POST /resource HTTP/1.1Host: example.comContent-Type: application/jsonPrefer: return=minimal{"id":123, "name": "abc"}

The server responds with a201, but does not include any response body.TheLocation header contains a URL with the location of the newly-created resource.There's no need to include aPreference-Applied header because the absence of a response body is readily apparent:

HTTP/1.1 201 CreatedLocation: /resource?id=123

Requesting asynchronous processing

This example requests the server start an async processing task:

POST /process HTTP/1.1Host: example.comPrefer: respond-async{  "task": "check-broken-links"}

The server responds with a202 Accepted response indicated the request has been accepted and has not yet completed executing asynchronously.ALocation header points to a status monitor that represents the state of the processing:

HTTP/1.1 202 AcceptedLocation: http://example.com/tasks/123/status

Providing multiple preferences

The following request includes two preferences;timezone=Jupiter/Red_Spot indicating a time zone preference for the client, andhandling=strict for strict validation:

GET /events HTTP/1.1Host: example.comPrefer: handling=strict, timezone=Jupiter/Red_Spot

In this implementation, an invalid time zone will throw an error:

HTTP/1.1 400 Bad Request

Specifications

See also

• Preference-Applied
• Prefer header on docs.oasis-open.org
• Prefer header on docs.postgrest.org