HTTP Headers in REST API Design — Complete Guide

In this tutorial, you will learn about HTTP Headers in REST Api Design. We cover key concepts, practical examples, and best practices to help you master this topic.

HTTP headers are metadata sent with requests and responses in REST APIs that convey information about authentication, Caching, content type, Rate Limiting, and security between client and server.

flowchart TD
  A[HTTP Headers] --> B[Request Headers]
  A --> C[Response Headers]
  A --> D[Representation Headers]
  B --> B1[Authorization]
  B --> B2[Accept]
  B --> B3[Content-Type]
  C --> C1[Cache-Control]
  C --> C2[RateLimit-Remaining]
  C --> C3[Location]
  style A fill:#e1f5fe
  style B1 fill:#fff9c4
  style C1 fill:#c8e6c9

Headers are grouped by their role. Request headers like Authorization carry credentials. Response headers like RateLimit-Remaining convey server information. Representation headers like Content-Type describe the body format. Entity headers like ETag support caching.

Think of HTTP headers like the envelope of a letter. The letter inside is the body. The envelope contains metadata: who sent it (Authorization), how to read it (Content-Type), when it was sent (Date), and how to handle it (Cache-Control).

Example: Common Request Headers

import requests

headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "Accept": "application/json",
    "User-Agent": "MyApp/1.0",
    "X-Request-ID": "550e8400-e29b-41d4-a716-446655440000"
}
response = requests.get(
    "https://api.example.com/users/42",
    headers=headers
)
print(f"Status: {response.status_code}")

Expected output:

Status: 200

Example: Reading Response Headers

import requests

response = requests.get("https://api.example.com/users/42")
print("=== Response Headers ===")
print(f"Content-Type: {response.headers.get('Content-Type')}")
print(f"Cache-Control: {response.headers.get('Cache-Control')}")
print(f"ETag: {response.headers.get('ETag')}")
print(f"X-Request-ID: {response.headers.get('X-Request-ID')}")

Expected output:

=== Response Headers ===
Content-Type: application/json
Cache-Control: max-age=3600, private
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

Example: Custom Headers for Pagination

import requests

response = requests.get(
    "https://api.example.com/users",
    params={"page": 2, "per_page": 10}
)
print(f"X-Total-Count: {response.headers.get('X-Total-Count')}")
print(f"X-Page: {response.headers.get('X-Page')}")
print(f"X-Per-Page: {response.headers.get('X-Per-Page')}")
print(f"Link: {response.headers.get('Link')}")

Expected output:

X-Total-Count: 150
X-Page: 2
X-Per-Page: 10
Link: <https://api.example.com/users?page=1>; rel="prev", <https://api.example.com/users?page=3>; rel="next"

Common Mistakes

1. Exposing internal server information in headers — Headers like X-Powered-By or Server reveal technology stacks that attackers can exploit. Remove them in production.
2. Using incorrect header casing — HTTP headers are case-insensitive, but using standard casing (like Content-Type) improves readability and compatibility.
3. Not including a Date header — The Date header is required by HTTP/1.1. It helps clients correlate responses with their local time.
4. Overloading custom headers — Use standard headers wherever possible. Custom X- headers should be a last resort for API-specific metadata.
5. Forgetting CORS headers — Browser-based clients need Access-Control-Allow-Origin and related headers to read your API responses.

Practice Questions

1. What is the difference between an entity header and a representation header?
2. Why should you avoid exposing X-Powered-By headers?
3. What is the purpose of the ETag header?
4. Which header would you use for rate limiting information?
5. Challenge: Inspect the headers returned by a REST API like GitHub or JSONPlaceholder. Identify all request and response headers and classify them by type.

FAQ

Mini Project

Write a Python script that sends a request to a REST API and prints all response headers grouped by category (request, response, representation, entity). Then simulate adding custom headers to a POST request and verify they are received by the server.

What's Next

Now learn about request body formats in REST API Design.