Request Body with Pydantic

What you will be able to do

• ✓Explain what a request body is and when to use one
• ✓Describe a JSON body with a Pydantic model: required, optional and default fields
• ✓Read the 422 errors a body produces
• ✓Know which conversions Pydantic does on its own
• ✓Combine a body with path and query parameters
• ✓Stop typos with extra="forbid"

Words you will see in this lesson

A few words about bodies and models.

An everyday example: a form at the bank

When you open a bank account you fill in a printed form: name, date of birth, address, phone (optional). The clerk checks it before doing anything: every required box filled? Date in the right format? If not, the form comes back with each problem marked.

A Pydantic model is that printed form. The fields are the boxes, the types are the rules, defaults are the boxes you may leave empty. FastAPI is the clerk: it checks the JSON against the form and returns every problem at once.

Example 1 - a model and POST /books

BookIn lists what a client must send. title, author and pages have no default, so they are required. price has a default (0.0) and summary may be None, so both are optional.

create_book(book: BookIn) is all FastAPI needs: an argument whose type is a Pydantic model is read from the JSON body. Inside, book is a real object - book.title, book.pages. We return it, its type name, and model_dump() so you can see each form.

The other routes show more cases: body + path + query together, two body parameters, and Body(embed=True) for a single value.

What Pydantic accepts, converts and refuses

We changed one thing at a time. Missing author: 422 "Field required" at ["body", "author"]. Missing author AND pages: one 422 with TWO entries - Pydantic reports every problem at once, so the client can fix them all in one go.

Conversions: pages as the text "210" was accepted as 210, and 210.0 as 210 - the meaning is clear. 210.5 was refused: "got a number with a fractional part". summary: null was fine, because the field allows None.

Extra fields: we sent "isbn": "123", which BookIn does not have. No error - it was simply dropped. Keep that in mind; the next section shows why it matters.

The typo trap - and the fix

Here is why dropped fields matter. A client sends {"title": "Web APIs", "prise": 19.5} - "prise" is a typo for "price". FastAPI drops "prise", uses the default price 0.0, and answers 200. The book is saved for free, and nobody sees an error.

One line fixes it: model_config = ConfigDict(extra="forbid"). Now unknown fields are an error: 422 "Extra inputs are not permitted" at ["body", "prise"]. The client sees the typo at once. Use it for models that receive data from clients, especially when fields have defaults.

Watch out: The loose version answered 200 and stored price 0.0. No error, no warning - the most expensive kind of bug. extra="forbid" turns it into a clear 422.

It must really be JSON

A model body must arrive as a JSON object with the JSON content type. We tried three other ways and all three got 422 "Input should be a valid dictionary or object to extract fields from".

Form data (like an HTML form sends) is not JSON - Module 3 shows how to receive forms. JSON text sent WITHOUT the header Content-Type: application/json was refused too: the header tells FastAPI how to read the body. And a JSON list [ ... ] is not an object. With TestClient and httpx, json=... sets the header for you; with curl, add -H "Content-Type: application/json" (Lesson 1.3).

Body, path and query together

One request can use all three. In update_book, shop_id and book_id are in the path pattern, so they come from the path. book is a Pydantic model, so it comes from the body. notify is a simple type that is not in the path, so it comes from the query. PUT /shops/4/books/2?notify=true with a JSON body filled all four.

That is FastAPI’s rule: in the path pattern -> path; a Pydantic model -> body; a simple type otherwise -> query.

Two body values, and embed

add_review has two body parameters: a Review model and a reviewer string marked with Body(). With more than one, FastAPI expects each under its own name: {"review": {...}, "reviewer": "Ravi"}. Sending the review fields flat - {"stars": 5, "text": "Great", "reviewer": "Ravi"} - gave 422 "Field required" at ["body", "review"].

Body(embed=True) does the same for a single value: rate expects {"rating": 4}, not just 4. Sending the bare number 4 was refused. embed is useful when you want the JSON to have a clear name, even for one value.

Request bodies at a glance

class BookIn(BaseModel):
    title: str
    price: float = 0.0

def create_book(book: BookIn):

summary: str | None = None

book.model_dump()

model_config = ConfigDict(extra="forbid")

rating: Annotated[int, Body(embed=True)]

curl -X POST url -H "Content-Type: application/json" -d '{...}'

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

What usually goes wrong

✗ class BookIn(BaseModel):
    price: float = 0.0

✓ class BookIn(BaseModel):
    model_config = ConfigDict(extra="forbid")
    price: float = 0.0

✗ curl -X POST url -d '{"title": "x"}'

✓ curl -X POST url -H "Content-Type: application/json" -d '{"title": "x"}'

✗ {"stars": 5, "text": "Great", "reviewer": "Ravi"}

✓ {"review": {"stars": 5, "text": "Great"}, "reviewer": "Ravi"}

Practice

Write these yourself before opening anything. Getting them wrong first is most of how this sticks.

Quick check before you move on

Interview questions