Cookie Parameters

Cookie Parameters

🎯 What You'll Learn

This lesson covers how to read and validate HTTP cookies in your FastAPI endpoints using the Cookie class. Cookies are a fundamental part of web development, used to store small pieces of data on the client side.

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

- Read cookies from incoming HTTP requests

- Use FastAPI's Cookie class for type-safe cookie access

- Handle optional cookies with sensible default values

- Validate cookie values using Python type annotations

📚 Theory

What Are Cookies?

HTTP cookies are small pieces of data that a server sends to a client's web browser. The browser stores them and sends them back with subsequent requests to the same server. Cookies are commonly used for:

- Session management - Tracking user login sessions

- User preferences - Remembering theme, language, or layout choices

- Tracking - Recording user behavior across pages

How Cookies Work in HTTP

When a server wants to set a cookie, it includes a Set-Cookie header in its response:

[Code Example]

The browser then sends that cookie back in subsequent requests via the Cookie header:

[Code Example]

FastAPI's Cookie Class

FastAPI provides a Cookie class that works similarly to Query and Path, but reads values from the Cookie header instead of the URL.

[Code Example]

Without Cookie(), FastAPI would interpret session_id as a query parameter. The Cookie() default tells FastAPI to look in the cookie header instead.

🔧 Key Concepts

Required vs Optional Cookies

A required cookie has no default value. If the cookie is missing, FastAPI returns a 422 validation error:

[Code Example]

An optional cookie provides a default value, so the endpoint works even when the cookie is absent:

[Code Example]

Type Conversion

FastAPI automatically converts cookie string values to the declared Python type:

[Code Example]

If the conversion fails (e.g., a non-numeric string for an int cookie), FastAPI returns a 422 validation error with a clear error message.

Cookie vs Query vs Path

All three classes share the same interface but read from different parts of the request:

| Class | Source | Example |

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

| Query | URL query string | ?session_id=abc123 |

| Path | URL path | /users/abc123 |

| Cookie | Cookie header | Cookie: session_id=abc123 |

Practical Example

Here is a complete example combining required and optional cookies:

[Code Example]

When called with the header Cookie: session_id=abc123; theme=dark; language=en, the endpoint returns:

[Code Example]

🔗 What's Next?

In the next lesson, you'll learn about Header Parameters, where you'll discover how to read and validate HTTP headers using FastAPI's Header() class, including automatic hyphen-to-underscore conversion.

📖 Additional Resources

- FastAPI Official Tutorial - Cookie Parameters

- MDN Web Docs - HTTP Cookies

- RFC 6265 - HTTP State Management Mechanism