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 viaAccess-Control-Expose-Headers. - The
Varyresponse header is critical for any cached API response that depends onAuthorization; skip it and your CDN may serve user A's response to user B.
More primers
What is a REST API?
A plain-English explanation of REST, HTTP methods, resources, and why almost every modern web service speaks this style.
What is JSON?
JSON syntax in 5 minutes: objects, arrays, strings, numbers, why it replaced XML, and the gotchas that bite beginners.
What is HTTP?
Request/response, headers, methods, status codes - the protocol the web has run on since 1991.