Header Parameters
Part of: FastAPI Basics
Learn to read and validate HTTP headers using FastAPI's Header class. Handle common headers and custom X- headers.
What You'll Learn
- Use FastAPI's Header class to read HTTP headers
- Understand automatic hyphen-to-underscore conversion
- Handle custom X- headers for API authentication
- Work with optional headers and default values
Theory and Concepts
Header Parameters
🎯 What You'll Learn
This lesson covers how to read and validate HTTP headers in your FastAPI endpoints using the Header class. Headers carry metadata about the request and are essential for authentication, content negotiation, and request tracking.
By the end of this lesson, you'll understand how to:
- Read standard and custom HTTP headers in your endpoints
- Use FastAPI's automatic hyphen-to-underscore conversion
- Handle custom X- headers for API authentication and tracking
- Work with optional and required header parameters
📚 Theory
What Are HTTP Headers?
HTTP headers are key-value pairs sent with every HTTP request and response. They carry metadata about the request, the client, and the desired response format. Common request headers include:
- User-Agent - Identifies the client software making the request
- Accept-Language - Preferred language for the response
- Authorization - Credentials for authenticating the client
- Content-Type - Media type of the request body
- X-Request-Id - Custom header for tracking requests across services
FastAPI's Header Class
FastAPI provides a Header class that works like Query, Path, and Cookie, but reads values from HTTP request headers:
[Code Example]
Without Header(), FastAPI would treat user_agent as a query parameter. The Header() default tells FastAPI to look in the request headers instead.
Automatic Hyphen-to-Underscore Conversion
HTTP headers traditionally use hyphens as separators (e.g., User-Agent, Accept-Language), but Python variable names cannot contain hyphens. FastAPI automatically converts between the two:
[Code Example]
If you need to disable this conversion (rare), you can set convert_underscores=False:
[Code Example]
🔧 Key Concepts
Required vs Optional Headers
Required headers have no default value. If missing, FastAPI returns a 422 error:
[Code Example]
Optional headers provide a default value:
[Code Example]
Custom X- Headers
The X- prefix is a convention for custom, non-standard headers. They are widely used for:
- Authentication: X-Token, X-API-Key
- Request tracking: X-Request-Id, X-Correlation-Id
- Feature flags: X-Feature-Beta, X-Debug-Mode
[Code Example]
Header vs Query vs Path vs Cookie
All four classes share the same interface but read from different parts of the request:
| Class | Source | Example |
|----------|------------------|---------------------------------|
| Query | URL query string | ?token=abc123 |
| Path | URL path | /users/abc123 |
| Cookie | Cookie header | Cookie: token=abc123 |
| Header | Request headers | X-Token: abc123 |
Practical Example
Calling GET /headers/info/ with headers User-Agent: MyApp/1.0 and Accept-Language: en-US returns:
[Code Example]
Calling GET /secure/data/ with headers X-Token: supersecrettoken and X-Request-Id: req-123 returns:
[Code Example]
🔗 What's Next?
In the next lesson, you'll learn about Response Model, where you'll discover how to define and validate the shape of your API responses using Pydantic models and FastAPI's response_model parameter.
📖 Additional Resources
- FastAPI Official Tutorial - Header Parameters
- MDN Web Docs - HTTP Headers
- IANA Message Headers Registry
Helpful Hint
Import Header from fastapi. Note: header names with hyphens (like X-Token) automatically convert to underscores (x_token) in Python.