API Prefer Header: return=minimal and respond-async

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

The HTTP Prefer header lets API agents request optional response behavior such as minimal write responses or asynchronous handling.

## Core Explanation

Some APIs let clients influence how much work happens synchronously or how much representation data comes back after a write. Prefer is useful because it expresses a client preference without turning it into a required precondition.

Agents should record the Prefer value, response status, Preference-Applied header, response body shape, operation URL, and retry or polling policy. If a server ignores the preference, the agent still needs to parse the actual response rather than assuming a minimal body or an async job resource exists.

## Source-Mapped Facts

- RFC 7240 defines the Prefer request header field for clients to request optional server behaviors while processing a request. ([source](https://www.rfc-editor.org/info/rfc7240/))
- RFC 7240 defines the respond-async preference for cases where a client prefers asynchronous processing. ([source](https://www.rfc-editor.org/info/rfc7240/))
- MDN documentation describes the Prefer header as supporting preferences such as return=minimal and respond-async. ([source](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Prefer))

## Further Reading

- [RFC 7240 Prefer Header for HTTP](https://www.rfc-editor.org/info/rfc7240/)
- [MDN Prefer Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Prefer)