Skip to content

HTTP headers reference

A cheat-sheet of the headers GoRest uses, plus the 30 standard ones every developer encounters in the wild.

Headers are HTTP's metadata layer. They tell the server who you are, what you accept, and how you encoded the body; they tell the client what came back, how to cache it, and where to go next. This page is a reference, so bookmark it and look things up. The first three tables cover the headers every developer encounters; the last covers the ones specific to GoRest.

Standard request headers

Sent by the client. Most are optional, but Host is required and missing Content-Type on a body breaks most APIs.

Header Purpose Example
Accept Tells the server what response formats you can read. application/json, application/xml
Accept-Encoding Compression formats you accept (gzip, br, zstd). gzip, deflate, br
Accept-Language Preferred response language(s); usually ignored by APIs. en-US, en;q=0.9
Authorization Credentials. Bearer for API tokens, Basic for username:password, Digest for legacy. Bearer 4f8c9b...
Cache-Control On a request: do not return cached responses. On a response: how long the client may cache. no-cache, max-age=300
Content-Length Size of the body in bytes. Set automatically by HTTP libraries. 128
Content-Type Format of the body. Required when sending a body. application/json
Cookie All cookies set by previous responses, sent back automatically by the browser. session=abc; theme=dark
Host The hostname being requested. Required on HTTP/1.1. gorest.co.in
If-None-Match For ETag-based caching. Send the ETag from the last response; server returns 304 if unchanged. "abc123"
Origin Where the request came from. Browsers send it on cross-origin requests. https://app.example.com
Referer The page that linked to this request. Often used for analytics; can leak URLs. https://google.com/search
User-Agent Identifies the client software. Servers use it for analytics and (occasionally) feature gating. curl/8.4.0

Standard response headers

Sent by the server. Most matter for caching, security, or branching on what to do next.

Header Purpose Example
Cache-Control Caching rules: max-age, no-store, public, private, no-transform. public, max-age=300
Content-Type Format of the response body. application/json; charset=utf-8
Content-Length Size of the response body in bytes. 128
Content-Encoding Compression applied to the body. Client decompresses it without extra work. gzip
ETag Opaque hash of the resource for cache validation. "abc123"
Expires Deprecated absolute expiry date. Cache-Control replaced it. Wed, 21 Oct 2025 07:28:00 GMT
Last-Modified When the resource was last changed. Pair with If-Modified-Since requests. Wed, 21 Oct 2025 07:28:00 GMT
Location On 201 Created or 3xx redirect, where to go next. /users/4521
Retry-After On 429 or 503, how long to wait before retrying. Seconds or HTTP-date. 60
Set-Cookie Asks the client to store a cookie. HttpOnly + Secure + SameSite are essential for sessions. session=abc; HttpOnly; Secure; SameSite=Lax
Strict-Transport-Security Tells browsers: only ever talk to me over HTTPS, for this many seconds. max-age=63072000; includeSubDomains
Vary Which request headers cause different responses. Critical for shared caches. Accept, Authorization
WWW-Authenticate On 401, what auth scheme the server expects. Bearer realm="api"

CORS headers

Specific to cross-origin browser requests. Servers send them to tell the browser what is allowed; browsers refuse to expose responses if these headers are missing or wrong.

Header Purpose Example
Access-Control-Allow-Origin Origins allowed to read the response. * for public APIs, exact origin for credentialed. https://app.example.com
Access-Control-Allow-Methods Methods allowed on this resource. Returned by pre-flight OPTIONS responses. GET, POST, PATCH, DELETE
Access-Control-Allow-Headers Custom request headers the browser may send. Authorization, Content-Type
Access-Control-Allow-Credentials Whether the browser may include cookies in the request. true
Access-Control-Max-Age How long the browser may cache the pre-flight response (in seconds). 86400

GoRest response headers

GoRest v3 uses standard headers where one exists. Paging is in the body (meta) and in the standard Link header. Rate limits use the IETF RateLimit headers, not X-RateLimit-*. The older v2 API used X-Pagination-*, X-Links-* and X-RateLimit-*; see API v2 if you still use it.

Header Purpose Example
Link URLs of the first and next page of a list, with rel="first" and rel="next". No next on the last page. </public/v3/users?page%5Bafter%5D=eyJ2...>; rel="next"
ETag Version of the item or list. Send it back as If-Match on PATCH or DELETE to avoid lost updates (412 when it changed), or as If-None-Match on GET to get 304. "ba9604622f23dd33"
RateLimit-Policy Your limit: quota q and window w in seconds. 120 a minute per IP without a token. With a token it is the token's own limit (default 300, 1 to 600). "ip";q=120;w=60
RateLimit Calls left r and seconds until the window resets t. "ip";r=119;t=1
Retry-After On 429 and 503, seconds to wait before you retry. 1
Location On 201, the URL of the item you created. /public/v3/users/0190a8e4-0000-7000-8000-000000000001
Idempotency-Key Request header on POST. A retry with the same key within 24 hours gets the first answer again. 7d1c2b0e-5f4a-4b8e-9c3d-2a6f1e8b9d40
X-Request-Id Unique id for the request. Quote it in any bug report. Also in the request_id field of every error. 01a1933e-6df0-7b80-b270-9cd3a2f2ed85

Inspecting headers in the browser

Open DevTools, switch to the Network tab, click any request. The "Headers" sub-tab shows everything sent and received. For programmatic access on a GoRest response, use:

fetch(url).then(r => console.log([...r.headers]))

In a terminal, curl -i prints headers along with the body, and curl -I fetches only headers (HEAD request).

Tips

  • Header names are case-insensitive. Most libraries normalise to lowercase on access.
  • Custom headers no longer need an X- prefix per RFC 6648, but in practice everyone still uses it.
  • Browsers expose only a small set of response headers to JavaScript by default. To read custom ones (like RateLimit), the server has to allow them via Access-Control-Expose-Headers.
  • The Vary response header is critical for any cached API response that depends on Authorization; skip it and your CDN may serve user A's response to user B.
Continue reading

More primers