2026-09-23 · 8 min read
- http
- api
- reliability
The HTTP Prefer field lets clients express optional handling preferences without defining a new endpoint for every behavior. Common patterns request a minimal or full representation, a bounded wait, or asynchronous processing.
A preference is not automatically a requirement. The resource contract defines what the server supports, how it falls back, and when Preference-Applied tells the client which behavior influenced the response.
Define a preference support matrix
For every operation, list supported preference tokens, parameters, combinations, defaults, ignored cases, applied-response signaling, status codes, body schemas, and caching behavior. Keep extension tokens namespaced and documented.
- Parse fields with a standards-aware implementation.
- Ignore unknown preferences only where the protocol allows.
- Never make correctness depend on undocumented support.
- Expose stable fallback behavior to older clients.
Model return modes independently
For return=minimal, define which identifiers, validators, locations, warnings, and operation metadata remain available without a representation. For return=representation, specify the selected representation and authorization checks.
Clients should branch on status, documented fields, and actual body presence rather than assuming every successful mutation returns JSON. If preferences change cacheable representations, configure cache variation or prevent inappropriate storage.
Make asynchronous work durable
When respond-async is supported, define job creation, ownership, status resource, expiry, result retrieval, cancellation, retry timing, and terminal errors. Use idempotency controls so a client retry does not create duplicate side effects.
A wait preference can influence synchronous patience but should not create unbounded worker or connection lifetimes. Apply server budgets, queue limits, backpressure, and authorization on every status or result request.
Test negotiation through every hop
Use Flashman's URL tool for endpoint fixtures, JSON formatter for body schemas, diff for request and response fields, timestamp converter for wait timelines, and cron helper for async cleanup schedules.
Cover absent, supported, unknown, repeated, and malformed preferences; conflicting combinations; minimal and full returns; fast and slow completion; proxy forwarding; cache keys; retries; duplicate mutations; polling after expiry; cancellation; and mixed client versions.