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 custom headers
The X- prefix is the convention for non-standard headers. GoRest exposes pagination, rate-limit budget, and simulation flags this way.
| Header | Purpose | Example |
|---|---|---|
X-Pagination-Total |
Total rows matching the filter. On every list response. | 2884 |
X-Pagination-Pages |
Number of pages for the current limit. | 289 |
X-Pagination-Page |
The page you are on (1-indexed). | 1 |
X-Pagination-Limit |
Page size (default 10, max 100 via ?per_page=). | 10 |
X-Links-Previous |
Full URL of the previous page. Empty on page 1. When nothing matches, the three link headers are left out. | https://gorest.co.in/public/v2/users?page=1 |
X-Links-Current |
Full URL of the page you are on. | https://gorest.co.in/public/v2/users?page=2 |
X-Links-Next |
Full URL of the next page. Empty on the last page, so an empty value means you are done. | https://gorest.co.in/public/v2/users?page=3 |
X-RateLimit-Limit |
Per-token budget per minute (default 300, max 600). | 300 |
X-RateLimit-Remaining |
Calls left in the current window. | 88 |
X-RateLimit-Reset |
Seconds until the window resets. | 47 |
X-Request-Id |
Unique id for the request. Quote it in any bug report. | req_5g7H4Z |
X-Simulated-Status |
On forced-status simulation, confirms which status was forced. | 429 |
X-Simulated-Delay-Ms |
On delay simulation, confirms the delay applied (milliseconds). | 1500 |
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
X-RateLimit-Remaining), 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.