Response headers

Instructions for the client

Request headers tell the server about the client. Response headers tell the client about the response: what format the body is in, how to cache it, whether to store a cookie, where to find a resource. When you are building a server, setting the right response headers is just as important as sending the right status code.

Content-Type

The most important response header. It tells the client the format of the response body.

Content-Type: application/json             -> JSON
Content-Type: text/html; charset=utf-8     -> HTML
Content-Type: image/png                    -> PNG image
Content-Type: application/octet-stream     -> Binary data

The client uses Content-Type to decide how to handle the body. application/json means “parse this as JSON.” text/html means “render this as a web page.” image/png means “display this as an image.” Without this header, the client has to guess, and guessing leads to broken behavior.

Content-Length

The size of the response body in bytes.

Content-Length: 1234

The client uses this to know when the entire response has been received and to show download progress. If the server is streaming the response (sending it piece by piece), it might skip Content-Length and use Transfer-Encoding: chunked instead.

This is how the server tells the browser to store a cookie. The browser will automatically include this cookie in future requests to the same domain.

Set-Cookie: session=abc123; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=86400

There is a lot packed into that one header. Let’s walk through each part:

session=abc123 is the actual cookie: a key-value pair.

Path=/ means the cookie is sent on all paths. If you set Path=/api, it would only be sent on requests to /api/*.

HttpOnly means JavaScript cannot read this cookie via document.cookie. This is a security measure. If an attacker manages to inject JavaScript into your page (an XSS attack), they cannot steal the cookie.

Secure means the cookie is only sent over HTTPS. Never over unencrypted HTTP.

SameSite=Strict means the cookie is not sent on cross-site requests. This protects against CSRF attacks.

Max-Age=86400 means the cookie expires in 86,400 seconds (24 hours). Without Max-Age, the cookie is deleted when the browser closes. That is called a “session cookie.”

[!NOTE] The Authentication course covers cookie-based sessions in depth. The Web Security course explains why HttpOnly (XSS protection) and SameSite (CSRF protection) matter. This lesson explains the HTTP mechanism: the Set-Cookie header itself.

Location

Points the client to a resource. You have seen this header in two contexts already:

With 201 Created, it points to the newly created resource:

HTTP/1.1 201 Created
Location: /books/book-6

With 3xx redirects, it tells the client where to go:

HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/v2/books

Cache-Control

Tells the client how long it can cache this response before asking the server again.

Cache-Control: public, max-age=3600           -> cache for 1 hour
Cache-Control: private, no-cache              -> browser only, revalidate every time
Cache-Control: no-store                       -> never cache this

The Caching course covers this in much more detail. For now, just know it exists and what it controls.

Other useful headers

ETag is a fingerprint of the response content, used for conditional requests (from the Caching course).

Retry-After tells the client how many seconds to wait before retrying. Used with 429 (rate limited) and 503 (service unavailable).

Access-Control-Allow-Origin is the CORS permission header from the OPTIONS lesson.

X-Request-Id is a unique identifier for this request. Useful for debugging: if a request fails, the client can report the ID, and the server team can find it in the logs.

That covers the standard headers. But what about headers you invent yourself? The next lesson covers custom headers and when you might want them.

Exercises

Exercise 1: Set Content-Type: text/plain on a response that actually returns JSON. On the client side, try calling response.json(). What happens?

Exercise 2: Set a cookie with Set-Cookie. Make another request to the same domain. Find the cookie in the Cookie request header.

Exercise 3: Return a Location header with a 201 response. Follow the URL with another request to verify it points to the created resource.

What does the HttpOnly attribute on a cookie do?

Access Required