[ADP-136] Prefer

Overview

The Prefer header is used in HTTP requests to specify optional behaviors that the client would prefer the server to apply to the request processing. This header allows clients to indicate their preferences without mandating them, giving servers the flexibility to honor these preferences when possible.

Guidance

• Servers MUST ignore preferences they don't understand or can't honor.
• Clients MUST be prepared to handle responses as if the preference was not specified.
• APIs MUST use Prefer headers for optional behaviors only; don't rely on them for critical functionality.
• APIs SHOULD implement monitoring for Prefer header usage to understand client needs and API performance.
• If Prefer is supported, it MUST record the content of Prefer in the API documentation.

Server Response

• When a server honors a preference, it SHOULD include a Preference-Applied header in the response:

HTTP/1.1 202 Accepted
Preference-Applied: respond-async
Content-Type: application/json

{
  "status": "processing",
  "estimated_completion_time": "2023-06-15T14:30:00Z"
}

Semantic

Please refer ADP-355.

Related ADPs

• ADP-120: HTTP Headers
• ADP-355: Request with Preference
• ADP-767: Shared Common Headers

References

• RFC 7240: Prefer Header for HTTP
• MDN Web Docs: Prefer