Visual RFC.
ALL RFCs / RFC 7240
Read the RFC ↗

RFC 7240 / START HERE

HTTP Prefer, before the details

Prefer is an HTTP field name, not an acronym. HTTP means Hypertext Transfer Protocol, the request-and-response language used by websites and APIs.

It lets a client ask a server for optional behavior: return less data, include current resource data, accept work before it finishes or handle recoverable errors in a chosen way.

Start the guide See the 6 chapters ↓

The idea in one picture

  1. Ask for behavior

  2. Server chooses

  3. Read the response

A simplified picture of the idea; the chapters explain the actual mechanisms.

Why it exists

The server needs room to choose appropriate behavior without making every request a mandatory demand. RFC 7240 defines the fields and an initial preference set; RFC 8144 adds WebDAV-specific rules.

A familiar example

After updating a document, an app may ask for its current contents in the same response to save another request. The server may ignore the preference, so the client must inspect the actual response.

Helpful background

You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.

HTTPRFC 9110 · beginner overview ↗CachingRFC 9111 · beginner overview ↗HTTP PATCHRFC 5789 · beginner overview ↗

What you’ll learn next

Begin with chapter one, or choose a topic.

  1. Read optional preferencesPrefer lets an HTTP client ask for optional server behavior. A preference is a named hint, not a condition that must be satisfied.
  2. Report what was appliedPreference-Applied is an optional response field listing preferences the server honored. It does not repeat preference parameters.
  3. Wait without a deadline guaranteewait expresses a preferred processing interval in seconds after server receipt. respond-async asks for asynchronous handling: reply before the work finishes. Its completion protocol is not defined here.
  4. Choose the response bodyreturn=representation asks for current resource data; return=minimal asks for a small successful response. Neither dictates one universal status code.
  5. Handle recoverable errorshandling expresses strict or lenient processing preferences when a request has an error the server could recover from. The server still decides what is safe and processable.
  6. Keep cache variants separateA preference can change a response in ways that matter to a cache. Vary tells a cache which request fields were relevant to selecting a stored response.
Start with chapter one →

This introduction explains RFC 7240 (2014). Read the original RFC ↗