Request Handling in FastAPI: Params, Bodies & Headers

When clients talk to your API, they have several different ways of sending you data: values embedded in the URL, key-value pairs in the query string, a JSON body in the request payload, and metadata in request headers. FastAPI gives you clean, declarative ways to handle all of them — and it validates every piece of incoming data automatically, so you never have to write manual type-checking code. This lesson walks through each channel and shows you how to use the powerful Annotated validation style recommended in Pydantic v2.

Request Data Processing Flow

FastAPI intercepts incoming HTTP requests, extracts parameters from every part of the request, validates their types using Pydantic, and feeds the clean values directly into your route function.

Validation happens before your function is ever called. If any input fails, FastAPI immediately returns a 422 Unprocessable Entity with a detailed error message explaining exactly what went wrong.

Path Parameters

Path parameters are variables embedded directly inside the URL path. You define them using curly braces in the route, then add a matching function argument with a type annotation.

from fastapi import FastAPI

app = FastAPI()

# Sample mock database
EMPLOYEES = {
    1: {"name": "Alice", "department": "Engineering"},
    2: {"name": "Bob", "department": "Product"}
}

@app.get("/employees/{employee_id}")
def get_employee(employee_id: int):
    # FastAPI automatically validates that 'employee_id' is an integer
    employee = EMPLOYEES.get(employee_id)
    if not employee:
        return {"error": "Employee not found"}
    return employee

Define the variable in the path inside curly braces: /employees/{employee_id}.
Annotate employee_id: int in the function signature — if a user requests /employees/abc, FastAPI immediately returns 422 without you writing any checking code.

Validated Path Parameters

Use Path() with Annotated to enforce additional constraints:

from typing import Annotated
from fastapi import Path

@app.get("/employees/{employee_id}")
def get_employee(
    employee_id: Annotated[int, Path(gt=0, description="Must be a positive employee ID")]
):
    return {"employee_id": employee_id}

Query Parameters

Any function parameter that is not part of the path is automatically treated as a query parameter. They appear after the ? in the URL.

@app.get("/employees")
def list_employees(department: str | None = None, limit: int = 10):
    results = list(EMPLOYEES.values())

    if department:
        results = [
            emp for emp in results
            if emp["department"].lower() == department.lower()
        ]

    return results[:limit]

Request:

GET /employees?department=Engineering&limit=5

Use str | None = None for optional parameters.
Provide a default value directly (e.g., limit: int = 10).

Validated Query Parameters

from typing import Annotated
from fastapi import Query

@app.get("/employees")
def list_employees(
    page: Annotated[int, Query(ge=1, description="Page number")] = 1,
    limit: Annotated[int, Query(ge=1, le=100, description="Results per page")] = 20,
    department: Annotated[str | None, Query(alias="dept")] = None,
):
    return {"page": page, "limit": limit, "department": department}

The alias="dept" means clients send ?dept=Engineering but your parameter is named department in Python.

Request Bodies with Pydantic

When you need to send structured data — typically to create or update a resource — you use a request body with POST, PUT, or PATCH. Define the shape using a Pydantic model.

from pydantic import BaseModel, Field

class EmployeeCreate(BaseModel):
    name: str = Field(..., min_length=2, description="First and last name")
    department: str = Field(..., description="Assigned department")
    salary: float = Field(..., gt=0, description="Monthly base salary in USD")

@app.post("/employees")
def create_employee(employee: EmployeeCreate):
    new_id = max(EMPLOYEES.keys()) + 1 if EMPLOYEES else 1
    EMPLOYEES[new_id] = employee.model_dump()
    return {"id": new_id, "data": EMPLOYEES[new_id]}

FastAPI automatically:

Reads the request body as JSON
Validates it against EmployeeCreate
Creates an EmployeeCreate object and injects it as the employee parameter

Use employee.model_dump() to get a standard Python dictionary from the validated model.

Recommended `Annotated` Style

In Pydantic v2, the preferred approach separates the type from the validation metadata:

from typing import Annotated
from pydantic import BaseModel, EmailStr, Field

class Employee(BaseModel):
    name: Annotated[str, Field(min_length=3, max_length=50)]
    age: Annotated[int, Field(gt=0, lt=100)]
    email: EmailStr
    salary: Annotated[float, Field(ge=0)]

Both styles work, but Annotated is the recommended approach going forward.

Headers

You can read HTTP headers sent by clients using the Header class. FastAPI automatically converts snake_case parameter names to kebab-case header names.

from fastapi import Header

@app.get("/system-info")
def get_system_info(
    user_agent: str | None = Header(None),
    x_api_key: str | None = Header(None)
):
    return {
        "user_agent": user_agent,
        "api_key_sent": x_api_key is not None
    }

FastAPI maps x_api_key (Python snake_case) to the X-API-Key header (HTTP kebab-case) automatically. You don’t need to do anything special.

Validation Reference

Common Validation Options

Option	Purpose
`gt`	Greater than
`ge`	Greater than or equal
`lt`	Less than
`le`	Less than or equal
`min_length`	Minimum string length
`max_length`	Maximum string length
`pattern`	Regular expression match
`alias`	Alternate parameter name
`title`	Display title in API docs
`description`	Description in API docs

Useful Pydantic Types

Type	Purpose
`EmailStr`	Validates email addresses
`AnyUrl`	Validates URLs
`UUID`	Validates UUID values
`date`	Date only
`datetime`	Date and time
`Decimal`	High-precision decimal numbers

EmailStr requires the email-validator package. Install it with:

pip install email-validator

Putting It All Together

Here’s a complete example combining path parameters, query parameters, a request body, and validation in one file:

from typing import Annotated
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel, Field

app = FastAPI()

class ItemCreate(BaseModel):
    name: Annotated[str, Field(min_length=2, max_length=100)]
    price: Annotated[float, Field(gt=0)]
    in_stock: bool = True

ITEMS: dict = {}

@app.get("/items/{item_id}")
def get_item(
    item_id: Annotated[int, Path(gt=0)],
    include_details: bool = False
):
    return {"item_id": item_id, "details": include_details}

@app.get("/items")
def list_items(
    search: Annotated[str | None, Query(min_length=2)] = None,
    limit: Annotated[int, Query(ge=1, le=50)] = 10
):
    return {"search": search, "limit": limit}

@app.post("/items")
def create_item(item: ItemCreate):
    new_id = len(ITEMS) + 1
    ITEMS[new_id] = item.model_dump()
    return {"id": new_id, **ITEMS[new_id]}

SQL & Databases

Data Analysis

FastAPI

Frontend

Request Handling in FastAPI: Params, Bodies & Headers

Request Data Processing Flow

Path Parameters

Validated Path Parameters

Query Parameters

Validated Query Parameters

Request Bodies with Pydantic

Recommended `Annotated` Style

Headers

Validation Reference

Common Validation Options

Useful Pydantic Types

Putting It All Together

​Request Data Processing Flow

​Path Parameters

​Validated Path Parameters

​Query Parameters

​Validated Query Parameters

​Request Bodies with Pydantic

​Recommended Annotated Style

​Headers

​Validation Reference

​Common Validation Options

​Useful Pydantic Types

​Putting It All Together

Request Data Processing Flow

Path Parameters

Validated Path Parameters

Query Parameters

Validated Query Parameters

Request Bodies with Pydantic

Recommended `Annotated` Style

Headers

Validation Reference

Common Validation Options

Useful Pydantic Types

Putting It All Together