Prefer

What is the Prefer header?

The Prefer request header, defined in RFC 7240, lets a client indicate preferences for how a request is processed. Preferences are optional hints: the server may honor or ignore them without changing the outcome’s validity.

API Usage & Best Practices

• Control the response body: return=minimal asks the server to return little or no body, while return=representation asks for the full resource state.
• Request asynchronous processing: respond-async asks the server to process the request asynchronously, often answered with 202 Accepted; wait= bounds how long the client will wait.
• Confirm what was applied: When the server acts on a preference, it can echo it back in the Preference-Applied response header. RFC 7240 says this is only needed when the response does not already make it obvious, but return=minimal and return=representation are exactly the cases where a client cannot always tell, so send it for those.

Examples

POST /v1/orders HTTP/1.1
Host: api.example.com
Prefer: return=minimal, respond-async, wait=10