Prefer

Async & Long-Running IANA permanent request reached by regulation 2 spellings

Prefer lets a client state a preference the server may honour or ignore. The value that matters most in API work is respond-async: do not make me wait, hand me somewhere to poll.

That single token is load-bearing in US healthcare. The FHIR Bulk Data (Flat FHIR) specification enters its async flow with Prefer: respond-async, returns a polling location in Content-Location, and paces the client with Retry-After — and the CMS Interoperability and Prior Authorization rules require the bulk data capability. Three general-purpose HTTP headers, composed into a pattern, made mandatory by a federal rule.

Twenty-nine providers declare it, which is a reasonable proxy for how much of the catalog has a real async story.

The registry

Listed in the IANA HTTP Field Name Registry as a permanent entry. Defined in RFC 7240: Prefer Header for HTTP.

In the catalog

Declared by 29 providers across 520 published specification files in the API Evangelist catalog, where it appears as a request header — sent by the client.

It is spelled 2 different ways across those contracts — Prefer, prefer. HTTP field names are case-insensitive (RFC 9110, §5.1), so every one of these is the same header. They are not the same string, which is why generated clients disagree about it.

Reached by regulation

This header is mandated: the law, or a technical standard the law makes binding, names it directly. It is visible in a published OpenAPI or AsyncAPI, so the catalog can count it.

Using it

If you accept respond-async, respond 202 Accepted with a Content-Location pointing at a status resource and a Retry-After telling the client how long to wait. Echo what you honoured in Preference-Applied — a preference that is silently ignored is worse than one that is refused, because the client cannot tell.