HTTP headers
A selected guide to request and response fields that describe content, caching, authentication, redirects, and retries.
Read as MarkdownRead a field in its message
HTTP header fields appear before message content. Their names are case-insensitive, but the meaning of a field depends on whether it is in a request or response and on the status and method. This is a selected guide, not a complete field registry; consult IANA for current field assignments.
Header values can contain credentials or personal data. Do not copy Authorization or Cookie values into logs, bug reports, or example URLs.
Request: Accept: application/json
Response: Content-Type: application/jsonContent and negotiation
Accept in a request expresses which response media types the client prefers. Content-Type describes the media type of the content in the message carrying it, whether that message is a request or a response. Content-Encoding identifies content codings applied to the representation; decode those codings before interpreting the media type.
A successful status alone does not identify the content format. Inspect Content-Type before parsing a response, and check Content-Encoding when handling encoded content.
Accept: application/json
Content-Type: application/json
Content-Encoding: gzipValidators and cache control
A response ETag is a representation validator. A later conditional GET can send If-None-Match with that value; a matching condition can produce 304 Not Modified so the client can reuse a stored response. A validator is not, by itself, permission to store a response.
Cache-Control: no-store tells caches not to store the response. Cache-Control: no-cache allows storage but requires successful validation before reuse. Vary names request fields that affect which stored response can be reused, such as Accept-Encoding. Apply the directives and Vary together when deciding whether a cached response fits a new request.
ETag: "example-v1"
If-None-Match: "example-v1"
Cache-Control: no-cache
Vary: Accept-EncodingRedirects and access
Location identifies the target URI for a redirect response. On 201 Created, it can identify the newly created resource. A 401 response carries WWW-Authenticate with at least one challenge; a client can send Authorization credentials for a protected resource. Never treat a redirect target as permission to forward credentials to another origin.
A 405 Method Not Allowed response includes Allow to list methods currently supported by the target resource. Read it before choosing another method.
Location: /new-resource
WWW-Authenticate: Bearer realm="example"
Authorization: Bearer <redacted>
Allow: GET, HEADRetry guidance
Retry-After can appear with 503 Service Unavailable to suggest how long a service is expected to be unavailable, and with a redirect to suggest a delay before following it. A 429 Too Many Requests response may include Retry-After to suggest when to try again. The value is either a non-negative number of seconds or an HTTP date.
The header is advice about timing, not a guarantee that a retry will succeed. Before repeating a request, consider whether repeating its method and body can repeat an effect.
Retry-After: 120
Retry-After: Wed, 21 Oct 2015 07:28:00 GMTSources
KEEP EXPLORING
Open the waypoint directory