Preference-Applied

When a server honors optional behaviors from the Prefer request header, the Preference-Applied response header confirms which preferences were applied during processing.

Table of Contents

Usage
Values
Example
Echo without parameters
See also

Usage

The Preference-Applied header is part of the HTTP Prefer framework. Clients use the Prefer request header to request optional behaviors during request processing. The server responds with Preference-Applied to confirm which preferences were applied.

Servers send Preference-Applied only when confirmation adds value for the client. If the response format makes clear which preferences were honored (for example, an empty response body when return=minimal was requested), the header is unnecessary. The header is most useful when preferences affect server-side processing in ways not visible in the response structure.

The Preference-Applied syntax lists preference tokens with their values but without additional semicolon-delimited parameters. If the server honors return=representation from the request, the response includes Preference-Applied: return=representation. Multiple preferences are separated by commas.

Common preference tokens include return, respond-async, wait, and handling. The server applies these selectively based on capabilities and request context. A server might honor return=minimal while ignoring wait=10 if the operation completes immediately.

The header is widely used in APIs following the Prefer specification, including PostgREST and other systems supporting client-driven response formats.

Values

return

The return preference token confirms the server honored the client's request for a specific response format. Common values include return=representation (full resource representation) and return=minimal (minimal or no response body).

respond-async

The respond-async preference token indicates the server honored the client's request to process the operation asynchronously. The server typically responds with 202 Accepted and includes a Location header pointing to a status endpoint.

wait

The wait preference token confirms the server honored a client-specified maximum wait time in seconds before responding. The server returns within the specified duration, even if processing is incomplete.

handling

The handling preference token indicates how the server handled the request. The value handling=strict confirms strict validation, while handling=lenient indicates relaxed processing of edge cases.

Example

A client requests a minimal response after creating a resource. The server processes the request and confirms the preference was applied.

Preference-Applied: return=minimal

A server processing multiple preferences confirms all honored tokens in a single header.

Preference-Applied: return=representation, wait=10

An API supporting asynchronous processing responds with 202 Accepted and confirms the async preference.

HTTP/1.1 202 Accepted
Preference-Applied: respond-async
Location: /status/abc123

PostgREST APIs commonly send Preference-Applied to confirm custom return formats and resolution preferences.

Preference-Applied: return=headers-only

Echo without parameters

Preference-Applied echoes the token, never the parameters. A request carrying a Prefer value with parameters gets back the bare token, by design, so string-comparing the two headers fails on any parameterised preference.

The echo exists for the ambiguous cases. A response honoring return=minimal and one omitting a body for other reasons look identical, so the header is the only reliable signal a preference was applied, and the specification leaves sending the echo optional, so absence proves nothing either.

OData turns the courtesy into a contract. The OASIS protocol requires the echo for respond-async, allow-entityreferences, callback, and omit-values, and for maxpagesize the echoed number is allowed to differ from the request, the server clamping the page size and reporting the applied value, which is the clearest demonstration of why an echo beats an assumption. Microsoft's OData stack, the base under Microsoft Graph, implements the echo, with individual Graph endpoints inconsistent about returning the header.