HTTP headers

Headers carry everything about a message that is not its content: who is calling (Authorization), what format the body is in (Content-Type), what format the client wants back (Accept), how long it may be cached (Cache-Control), which version it is (ETag) and when to try again (Retry-After). Names are case-insensitive; values are text.

How it works

A request or response is a start line, then headers one per line, then an empty line, then the body. Intermediaries read and add headers without touching the body — a proxy adds Via, a load balancer X-Forwarded-For, a CDN its own cache status. Many behaviours that look like API features are really header conventions.

The misconception

That asserting on the body is enough. Some of the most consequential bugs live only in headers: a missing Location after a 201, a Cache-Control that lets a private response be cached by a CDN, a Content-Type of text/html on a JSON body. They pass every body assertion.

Try it here

Every response in the docs panel shows its headers next to the body, and the assertion language reads them with headers.<name> — try headers.etag exists on GET /football/v1/standings.

Sources

Other terms

Content negotiation — Client and server agreeing on the format of a response, through headers rather than separate URLs.
ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
REST API — An API that models a system as addressable resources, manipulated with standard HTTP methods.
API endpoint — One URL plus one HTTP method — the smallest unit of an API that a client can call.
Query parameters — The key=value pairs after the ? in a URL, used to filter, sort, page or shape what an endpoint returns.
Path parameters — A variable segment of a URL path, such as the 42 in /orders/42, that identifies one specific resource.

All glossary terms · Testing techniques · All 39 mock REST APIs

Last updated 16 October 2026