HTTP essentials: headers, authorization, cookies, payloads, versioning

1. Overview

HTTP is a request–response protocol where clients send requests to servers and receive responses. While the body carries data, headers are the metadata that describe how to process, authenticate, cache, compress, and route those messages.

2. HTTP messages and headers

HTTP headers are present on both requests and responses and govern authentication, caching, content negotiation, cookies, CORS, proxies, and more. Some headers are end-to-end (travel from client to origin server), while others are hop-by-hop (apply only to a single transport hop and should not be forwarded). Cookies are also transmitted via headers and enable maintaining application state over stateless HTTP.

2.1 Structure examples

GET /api/products?category=books HTTP/1.1
Host: api.example.com
User-Agent: MyApp/1.0
Accept: application/json
Authorization: Bearer <token>
Cookie: sessionId=abc123; theme=light

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 342
Cache-Control: private, max-age=60
ETag: "5f2a-1a6"
Set-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Lax

{ "items": [ ... ] }
  

2.2 Common header families

• Authentication: WWW-Authenticate, Authorization.
• Cookies: Cookie, Set-Cookie.
• Caching: Cache-Control, Expires, ETag, If-None-Match, Last-Modified.
• Content/payload: Content-Type, Content-Length, Content-Encoding, Content-Language.
• Content negotiation: Accept, Accept-Language, Accept-Encoding.
• Redirects: Location.
• Proxies: Forwarded, X-Forwarded-For, Via.
• CORS: Access-Control-Allow-Origin, Access-Control-Allow-Credentials, etc.

These families cover how clients and servers exchange capabilities, identities, and constraints, and how intermediaries handle the message across the chain.

3. Authorization header

The Authorization request header carries credentials to authenticate the client to the server. Typically, a client first requests a protected resource without credentials, the server replies with 401 Unauthorized and a WWW-Authenticate header indicating acceptable schemes; the client then retries with Authorization. Common schemes include Basic, Digest, Bearer (tokens like JWT), and others; syntax: Authorization: <scheme> <parameters>.

3.1 Examples

# Bearer token (e.g., OAuth2/JWT)
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# Basic (base64(username:password) over TLS only)
Authorization: Basic dXNlcjpzZWNyZXQ=
  

• Always prefer TLS: Send credentials only over HTTPS.
• Least privilege: Scope tokens to what the client needs.
• No storage leaks: Avoid logging full Authorization headers.

4. Cookies

Cookies are sent by clients using the Cookie header and set by servers using Set-Cookie. They are commonly used for session continuity and preferences, and include attributes like HttpOnly, Secure, and SameSite to constrain how browsers send and expose them.

4.1 Examples and flags

# Server to client:
Set-Cookie: sessionId=abc123; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=1800

# Client to server:
Cookie: sessionId=abc123; theme=light
  

• HttpOnly: Inaccessible to JavaScript; mitigates XSS stealing cookies.
• Secure: Cookie sent only over HTTPS.
• SameSite: Controls cross-site sending (Strict, Lax, None).
• Scope: Use Path and Domain precisely to limit exposure.

5. Payloads and content negotiation

The message body (payload) is described by representation headers like Content-Type (media type and charset) and Content-Encoding (compression), while payload headers like Content-Length specify size. Clients use Accept, Accept-Language, and Accept-Encoding to indicate preferred formats; servers respond accordingly, often with Content-Type and related headers.

5.1 Examples

# Client requests JSON and gzip
Accept: application/json
Accept-Encoding: gzip

# Server responds with JSON compressed
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
Content-Length: 1024
  

• Content-Type: Be explicit (e.g., application/json; charset=utf-8).
• Compression: Use gzip/br for large responses when clients accept them.
• Integrity: ETags with If-None-Match enable conditional requests and caching.

6. API versioning strategies

Versioning lets you evolve APIs without breaking clients. Common approaches: URL path (/v1/orders), query parameter (?api-version=1.0), and header-based versioning (e.g., media type negotiation or custom header). Header-based versioning keeps URLs clean and uses Accept (e.g., application/vnd.example.v2+json) or a custom header like X-API-Version, but requires clear documentation and caching considerations.

6.1 Header-based versioning example

GET /orders HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v2+json

HTTP/1.1 200 OK
Content-Type: application/vnd.example.v2+json
{ "data": "This is version 2 response" }
  

• Discoverability: Document how clients specify versions.
• Default: Define a safe default version when none is provided.
• Caching: Ensure caches vary by version header/media type.
• Deprecation: Communicate timelines and migration paths.

7. Other key elements to know

• Caching: Use Cache-Control (e.g., max-age, no-store), validators like ETag/If-None-Match, and Vary to control freshness and revalidation.
• CORS: Cross-origin access is governed by headers like Access-Control-Allow-Origin, Access-Control-Allow-Methods, and preflight OPTIONS behavior.
• Redirects: Servers signal new locations using Location with 3xx status codes.
• Proxies and client IP: Forwarded or X-Forwarded-For reveal upstream client/protocol information for apps behind load balancers.
• Range requests: Range and Accept-Ranges enable partial content delivery for large files and resumable downloads.
• Security headers: Consider Content-Security-Policy, Strict-Transport-Security, Referrer-Policy, and X-Content-Type-Options for defense-in-depth.

8. Quick best practices

• Authenticate safely: Use HTTPS, short-lived tokens, and the least-privilege scopes.
• Protect sessions: HttpOnly + Secure + appropriate SameSite on cookies.
• Be explicit about types: Always set accurate Content-Type and Content-Length (or chunked transfer).
• Design for caching: Use Cache-Control, ETag, and Vary intentionally.
• Version with intent: Choose a versioning strategy that fits your clients and document it clearly.
• Log with care: Never log secrets or full Authorization headers; redact tokens.