HTTP Headers Explained — The Metadata of Every Request and Response

What You'll Learn

• What HTTP headers are and why they exist
• The headers you will use in every API call
• Request headers vs response headers
• How content negotiation works via Accept and Content-Type

Why This Matters

Headers carry the metadata that surrounds every HTTP message. Without Content-Type, the server does not know if your body is JSON or XML. Without Authorization, it does not know who you are. Without Accept, it does not know what format to respond in. If you do not understand headers, you cannot debug "400 Bad Request" or "415 Unsupported Media Type" errors.

Simple Explanation

A header is a single line at the top of an HTTP message, formatted as Name: Value. Headers come right after the request line (or status line) and before the blank line that ends the headers section.

GET /users/123 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOi...

[blank line]

Each header carries one piece of metadata. Multiple headers stack together to describe the request.

Header Naming Convention

• Names are case-insensitive: Content-Type, content-type, and CONTENT-TYPE are all the same.
• Convention: hyphen-separated, title-case (Content-Type, User-Agent).
• Custom headers often start with X- (e.g., X-Request-Id), though this convention is no longer required by RFC 6648.

Request Headers You Will Use Daily

Host

The domain name of the server. Required in HTTP/1.1 because one IP can serve many domains.

Host: api.example.com

Accept

Tells the server what content types the client can handle in the response. The server uses this to choose the response format.

Accept: application/json
Accept: application/xml
Accept: */*

Content-Type

Tells the server what format the request body is in. Required whenever there is a body (POST, PUT, PATCH).

Content-Type: application/json
Content-Type: application/x-www-form-urlencoded
Content-Type: multipart/form-data

Authorization

Carries credentials that prove who the client is. Most common format is Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Covered in depth in Module 5.

User-Agent

Identifies the client software. Servers use it for analytics and sometimes for routing.

User-Agent: curl/7.81.0
User-Agent: MyApp/1.0 (https://example.com)

Accept-Encoding

Tells the server the client can accept compressed responses (gzip, br). Most clients set this automatically.

Accept-Encoding: gzip, deflate

Response Headers You Will Use Daily

Content-Type

Tells the client what format the response body is in. Should always match what the client requested via Accept (or the server's default).

Content-Type: application/json; charset=utf-8

Content-Length

The size of the response body in bytes. Lets the client know when the response is complete.

Content-Length: 247

Cache-Control

Tells caches (browser, CDN, proxy) how long they can store the response.

Cache-Control: max-age=3600, public
Cache-Control: no-cache, no-store, must-revalidate

ETag

A hash of the resource's current state. The client can send it back as If-None-Match on the next request. If the resource has not changed, the server returns 304 Not Modified instead of resending the body.

ETag: "abc123"
If-None-Match: "abc123"

Location

Used with 201 Created (and 3xx redirects) to point to the new resource's URL.

Location: https://api.example.com/users/123

Retry-After

Used with 429 Too Many Requests or 503 Service Unavailable to tell the client how long to wait before retrying.

Retry-After: 60

Content Negotiation — How Accept and Content-Type Work Together

The client sends Accept to say what it wants. The server sends Content-Type to say what it actually returned. These should agree.

# Client asks for JSON
GET /users/123 HTTP/1.1
Accept: application/json

# Server agrees and returns JSON
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "Anita"}

If the client asks for XML and the server only supports JSON, the server may return 406 Not Acceptable or just return JSON anyway (most APIs do the latter).

Common Mistakes

1. Forgetting Content-Type on a POST/PUT body. The server has no way to know your body is JSON, so it returns 415 Unsupported Media Type or parses it as form data.
2. Sending the wrong Accept header. If you set Accept: text/html on an API that only returns JSON, you may get an error or HTML error page.
3. Putting credentials in custom headers. Use Authorization for tokens. Custom headers can be stripped by proxies or load balancers.
4. Hard-coding Content-Type: application/json for form posts. Forms use application/x-www-form-urlencoded or multipart/form-data. Wrong type = silent data loss.
5. Treating headers as case-sensitive. They are not. content-type and Content-Type are equivalent, but stick with one style for readability.

Practical Exercise (5 minutes)

Run this cURL command and inspect the response headers:

curl -I -H "Accept: application/json" https://jsonplaceholder.typicode.com/posts/1

The -I flag fetches only headers. Note:

1. The value of Content-Type in the response.
2. The value of Cache-Control (or its absence).
3. The value of Content-Length.
4. Whether ETag is set.

Mini Challenge

Send the same request twice to JSONPlaceholder. First, set Accept: application/xml. Then set Accept: text/html. Does the server respect the header and change its response format? (Some do, some don't — observing this teaches you how content negotiation actually works in practice.)

Key Takeaways