HTTP Headers

Prefer header

HTTP Header

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

Note:
Browsers have no handling for the Prefer and Preference-Applied headers: they are used in custom, implementation-specific clients.
Ensure both client and server support this header before relying on it in production.

Servers should silently ignore preferences that they do not support, as though the header were not present.

Header type	Request header
Forbidden request header	No

Syntax

Prefer: <preference>, <preference>, ...

Directives

respond-async: The client prefers asynchronous processing. For instance, the server might send a 202 Accepted response, indicating that the request was received. This response would also include a Location header containing a URL that the client can use to monitor the processing status.
return=minimal: Requests that the server send back only essential content (a headers-only response).
return=representation: Asks for a complete resource representation in the server’s reply.
wait=<seconds>: The maximum duration in seconds within which the client expects a response from the server, measured from when the request was received. If the respond-async preference is also specified, the server should process asynchronously if the request will exceed the wait time. Otherwise, the server assumes the client will time out after the designated wait period (response behavior depends on the server’s implementation).
handling=lenient: The client wishes the server to apply relaxed validation and error management during request processing.
handling=strict: The client wishes the server to apply rigorous validation and error management during request processing.
Custom preference: Vendors or applications can define their own preferences to meet specific requirements. For example, Prefer: timezone=America/Los_Angeles.

Example

Requesting minimal response:

The following request asks for a minimal response. This typically means a headers-only response, unlike return=representation where a full representation is included in the response body:

POST /resource HTTP/1.1
Host: example.com
Content-Type: application/json
Prefer: return=minimal


{"id":123, "name": "abc"}

The server responds with a 201 Created status but does not include any response body. The Location header provides a URL for the newly created resource. There’s no need for a Preference-Applied header because the absence of a response body is evident:

HTTP/1.1 201 Created
Location: /resource?id=123

Requesting asynchronous processing:

This example requests the server to begin an asynchronous processing task:

POST /process HTTP/1.1
Host: example.com
Prefer: respond-async


{
"task": "check-broken-links"
}

The server responds with a 202 Accepted status, indicating that the request has been received and is being executed asynchronously. A Location header points to a status monitor URL that represents the state of the processing:

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

Providing multiple preferences:

The following request includes two preferences: timezone=Jupiter/Red_Spot, which indicates a time zone preference for the client, and handling=strict for strict validation:

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

In this particular implementation, an invalid time zone will result in an error:

HTTP/1.1 400 Bad Request

How to Modify Header using Requestly

Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the Prefer header. This is useful when you want to control how the server processes a request, such as asking for minimal responses or asynchronous handling during development and testing. Steps to Modify the Prefer Header:

Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Prefer.
- In the “Header Value” field, enter your preferred directive (for example, return=minimal or respond-async).
Set the URL condition: Specify the URL or pattern where this header should apply (for example, https://your-api.com/*).
Save the rule.

Once configured, Requestly will inject the Prefer header into all matching requests. For example, using Prefer: return=minimal asks the server to return only essential information in the response.

You might need to modify the Prefer header to test how your API behaves with different processing preferences, such as reduced payload responses or asynchronous operations. This helps you validate server behavior and optimize client-server interactions before deploying changes to production.