Header Parameter Models

Header Parameter Models

What You'll Learn

HTTP headers carry metadata with every request -- authentication tokens, content types, language preferences, and more. When your endpoint needs to read several headers, declaring them individually becomes repetitive. FastAPI 0.115+ lets you group headers into a Pydantic model.

By the end of this lesson, you'll understand how to:

- Group header parameters into Pydantic models

- Understand the automatic hyphen-to-underscore conversion

- Apply validation to groups of headers

- Handle optional and required header groups

Headers in HTTP

Every HTTP request includes headers. Some common ones:

[Code Example]

Headers are used for authentication, content negotiation, request tracking, and many other cross-cutting concerns.

Individual Header Parameters

Without header models, you declare each header separately:

[Code Example]

This works but gets unwieldy when you need many headers across multiple endpoints.

Header Parameter Models

With FastAPI 0.115+, you can group headers into a Pydantic model:

[Code Example]

The Header() annotation tells FastAPI to read each model field from the request headers.

Key Concepts

Hyphen-to-Underscore Conversion

HTTP headers traditionally use hyphens (X-Token, Accept-Language), but Python variable names cannot contain hyphens. FastAPI automatically converts between the two:

| HTTP Header | Python Field Name |

|--------------------|----------------------|

| X-Token | x_token |

| X-Request-ID | x_request_id |

| Accept-Language | accept_language |

This conversion happens transparently. You define your model fields with underscores, and FastAPI reads the corresponding hyphenated headers from the request.

Required vs Optional Headers

Fields without a default value are required. If the client does not send the header, FastAPI returns a 422 error:

[Code Example]

Validation

You can apply Pydantic validation to header fields:

[Code Example]

This ensures x_token is at least 10 characters and accept_language matches a locale pattern like en or en-US.

Reusability Across Endpoints

The same header model can be shared across multiple endpoints:

[Code Example]

Both endpoints require the same set of headers without duplicating the parameter declarations.

Combining with Other Parameter Types

Header models work alongside query parameters, path parameters, and request bodies:

[Code Example]

Best Practices

1. Mark authentication headers as required -- missing tokens should cause errors, not silent defaults

2. Provide defaults for preference headers like accept_language since not all clients set them

3. Use None for optional tracking headers like request IDs that may or may not be present

4. Group related headers -- separate authentication headers from preference headers into different models if needed

5. Add validation for security-sensitive headers like tokens to enforce minimum lengths

Common Mistakes

Forgetting the Header() annotation

[Code Example]

Using hyphens in field names

[Code Example]

What's Next?

You now know how to group headers into Pydantic models. Next, you will learn how to apply the same pattern to HTML form fields using Request Form Models.