Prefer general request

What it does

Prefer lets a client express a preference about how it would like a request handled — without demanding it as a hard requirement. Unlike Accept (which negotiates content type and is generally treated as a firm constraint), Prefer values are explicitly preferences: the server is free to honor them, partially honor them, or ignore them entirely, and the client needs to check the response (often via the companion Preference-Applied header) to know what actually happened.

This "advisory, not mandatory" nature is deliberate — it lets clients hint at desired behavior (like "process this asynchronously" or "just tell me it worked, skip the full response body") without breaking compatibility with servers that don't understand or support that particular preference.

Syntax

Prefer: <preference>
Prefer: <preference>, <preference>
Prefer: <preference>=<value>

Common preferences:

How it's used in practice

• API write operations with minimal responses — a client that doesn't need the full updated resource echoed back can send Prefer: return=minimal, letting the server skip serializing and transmitting a response body it doesn't need, saving bandwidth and server work on high-volume write endpoints.
• Long-running operations — Prefer: respond-async lets a client signal it's fine with the server kicking off a long-running job and returning immediately (typically 202 Accepted with a status-check URL) rather than holding the connection open until completion.
• Bounded synchronous waits for otherwise-async operations — combining respond-async with wait=5 tells the server "try to finish within 5 seconds and respond synchronously if you can; otherwise fall back to async and let me poll."
• OData and structured API ecosystems — Prefer sees particularly heavy, standardized use in OData-based APIs, where preferences around response minimality and representation format are a core part of the protocol's design.

Common mistakes and gotchas

Assuming a preference was honored without checking. Since Prefer is explicitly advisory, a server that doesn't support or chooses not to honor a given preference will simply process the request normally — the client needs to inspect the response (ideally via Preference-Applied, or by observing the actual response shape) rather than assuming its preference took effect.

Treating Prefer like a hard requirement in client code. If your client logic breaks when a preference isn't honored (for example, code that assumes return=minimal guarantees an empty body and crashes parsing a full response), you've built something fragile — always code defensively around the possibility a preference gets ignored.

Not implementing Preference-Applied server-side. Servers that support Prefer preferences but don't echo back Preference-Applied leave clients guessing whether their preference was actually honored, undermining the whole point of expressing a preference in a machine-checkable way.

Confusing Prefer with Accept. Accept negotiates representation format (JSON vs XML) and is treated as a much firmer constraint servers should respect via proper content negotiation. Prefer covers a broader, softer category of "how should this request be processed" hints that servers can freely decline.

Real-world examples

Minimal response preference on a write:

POST /api/orders HTTP/1.1
Prefer: return=minimal
Content-Type: application/json

{"item": "widget", "qty": 3}

HTTP/1.1 201 Created
Preference-Applied: return=minimal

(No response body, as requested.)

Async processing with a bounded wait:

POST /api/reports/generate HTTP/1.1
Prefer: respond-async, wait=10

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

FAQ

Is Prefer guaranteed to be honored by the server?

No — it's explicitly advisory. A server can support a given preference, partially support it, or ignore it entirely and process the request normally. Always design client code to handle both outcomes gracefully.

How do I know if my preference was actually applied?

Check the Preference-Applied response header, which servers that support Prefer are expected to include, listing which preferences were actually honored — its absence generally means none were applied (or the server doesn't implement this feedback mechanism at all).

What's the difference between Prefer and Accept?

Accept is a firmer content-negotiation mechanism specifically for representation format, and servers are expected to honor it (or respond 406 Not Acceptable if they truly can't). Prefer covers a broader category of processing hints that are explicitly optional for the server to honor.

Is Prefer commonly supported across APIs?

Support varies significantly — it's a well-established, standardized pattern (particularly strong in OData-based APIs) but far from universal across general REST APIs. Check your specific API's documentation to see which preferences (if any) it actually supports.

Fun fact

Prefer's deliberately advisory, non-binding design is a notable contrast to how most HTTP headers work — the vast majority of request headers either express a hard requirement (Content-Type) or a firm negotiation the server must respond to correctly (Accept). Prefer was specifically designed around graceful degradation: the entire point is that a client can send preferences to servers that have never heard of this header at all, and nothing breaks — the server just ignores what it doesn't understand and processes the request as it normally would, making it one of the more forward-compatible header designs in the HTTP ecosystem.