Preference-Applied
The HTTP Preference-Applied response header indicates which preferences from the Prefer request header the server honored when processing the request.
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
Takeaway
The Preference-Applied response header confirms which optional behaviors from the Prefer request header the server honored during request processing.