FastAPI: Pydantic for Robust Request Bodies

Why it exists

APIs often need to receive structured data from clients, like a JSON object to create a new user. Manually parsing this data, validating types, and handling missing fields is repetitive and error-prone. FastAPI needed a declarative way to handle this boilerplate work automatically.

The mental model

Think of a Pydantic model as a 'shape' or a contract for the data your endpoint expects in the request body. You define a Python class with typed attributes, and FastAPI guarantees that any data reaching your function will conform to that shape. It's like putting a bouncer at the door of your function who only lets in perfectly structured data.

How it works

You create a class that inherits from Pydantic's BaseModel. In your path operation function (e.g., for a POST request), you type-hint a parameter with this class. When a request comes in, FastAPI reads the body, parses the JSON, and uses your model to create an instance of your class. It automatically validates data types, checks for required fields, and returns a detailed validation error to the client if the data doesn't match. Inside your function, you interact with a clean, validated Python object, not a raw dictionary.

When to use it

Use a Pydantic model for the request body of any POST, PUT, or PATCH endpoint where the client sends structured data. This is the standard, idiomatic way to handle incoming data in FastAPI. It's especially powerful for complex, nested JSON objects, as Pydantic can handle nested models seamlessly.

When not to use it

Do not use a Pydantic model to define path parameters or query parameters. These are declared as separate, simple arguments to your path operation function (e.g., item_id: int, q: str | None = None). While you can use Pydantic for complex query parameter dependencies, the primary request body model is reserved for the data sent in the body itself. For simple form data (not JSON), you would use Form() instead.

One canonical example

First, import FastAPI and BaseModel. Then, define a class Item(BaseModel) with attributes like name: str and price: float. Finally, create a path operation @app.post("/items/") with a function async def create_item(item: Item):. When a client sends a POST request to /items/ with a JSON body like {"name": "Foo", "price": 42.0}, FastAPI validates the data and passes a full Item object to the create_item function. If the price were a string, FastAPI would automatically return a 422 Unprocessable Entity error.