Course topics

By WebNest Studio Engineering Team

Python Tutorial

Request Bodies and Pydantic Models

When a client creates or updates data it sends a JSON request body. FastAPI reads bodies through Pydantic models: classes that declare the expected fields and their types. Pydantic parses the JSON, converts types (a string "2026-09-27" becomes a date), checks every rule, and hands your function a fully validated Python object — or returns a detailed 422 error without ever calling it.

This lesson covers defining models, field constraints, nested models, custom validators, combining body, path and query parameters, and partial updates with PATCH.

Why it matters

Data sent to an API cannot be trusted: fields may be missing, of the wrong type or out of range. A Pydantic model states exactly what is acceptable, and FastAPI checks every request against it before your code runs. Pydantic is also used on its own for configuration and data processing, so the skill carries over.

Defining a Model

Subclass pydantic.BaseModel and annotate fields. Fields without defaults are required; str | None = None is optional. Field() adds constraints (gt, ge, min_length, max_length, pattern), defaults, aliases, descriptions and examples. Models can contain lists, dicts, other models, datetime, Decimal, Enum and more. A parameter typed as a model is read from the body; simple types stay path or query parameters.

Validators and Useful Methods

@field_validator("name") checks or transforms one field; @model_validator(mode="after") checks rules involving several fields (for example "end date after start date"). Raise ValueError with a helpful message to reject a value. Useful methods: model_dump() (to a dict), model_dump_json(), model_validate(data) (from a dict), model_copy(update=...), and model_dump(exclude_unset=True), which returns only the fields the client actually sent — the key to PATCH updates. model_config = ConfigDict(extra="forbid") rejects unknown fields.

PUT vs PATCH

PUT replaces the whole resource, so its model has the same required fields as creation. PATCH changes only some fields, so its model makes every field optional; merge model_dump(exclude_unset=True) into the stored data so omitted fields keep their current values.

Examples

Create and update books with Pydantic models

Python
from datetime import date
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field, field_validator

app = FastAPI()
books = {}

class BookIn(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    author: str
    price: float = Field(gt=0, description="Price in rupees")
    tags: list[str] = []
    published: date | None = None

    @field_validator("title", "author")
    @classmethod
    def tidy(cls, value: str) -> str:
        return " ".join(value.split())            # trim and collapse spaces

class BookPatch(BaseModel):                       # every field optional for PATCH
    title: str | None = None
    price: float | None = Field(default=None, gt=0)
    tags: list[str] | None = None

@app.post("/books", status_code=201)
def create_book(book: BookIn):
    book_id = len(books) + 1
    books[book_id] = book.model_dump()
    return {"id": book_id, **books[book_id]}

@app.patch("/books/{book_id}")
def patch_book(book_id: int, changes: BookPatch):
    books[book_id].update(changes.model_dump(exclude_unset=True))
    return {"id": book_id, **books[book_id]}

client = TestClient(app)
r = client.post("/books", json={"title": "  Python   Basics ", "author": "Asha",
                                "price": "450", "published": "2026-01-15"})
print(r.status_code, r.json())
print(client.patch("/books/1", json={"price": 399, "tags": ["sale"]}).json())
Output
201 {'id': 1, 'title': 'Python Basics', 'author': 'Asha', 'price': 450.0, 'tags': [], 'published': '2026-01-15'}
{'id': 1, 'title': 'Python Basics', 'author': 'Asha', 'price': 399.0, 'tags': ['sale'], 'published': '2026-01-15'}

Nested models, model validators and readable validation errors

Python
from datetime import date
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, ConfigDict, Field, model_validator

app = FastAPI()

class Address(BaseModel):
    city: str
    pincode: str = Field(min_length=6, max_length=6)

class OrderItem(BaseModel):
    product: str
    quantity: int = Field(ge=1, le=20)
    unit_price: float = Field(gt=0)

class Order(BaseModel):
    model_config = ConfigDict(extra="forbid")     # unknown fields are errors
    customer: str
    address: Address
    items: list[OrderItem] = Field(min_length=1)
    order_date: date
    delivery_date: date

    @model_validator(mode="after")
    def delivery_after_order(self):
        if self.delivery_date < self.order_date:
            raise ValueError("delivery_date must be on or after order_date")
        return self

@app.post("/orders")
def place_order(order: Order):
    total = sum(item.quantity * item.unit_price for item in order.items)
    return {"customer": order.customer, "city": order.address.city, "total": total}

client = TestClient(app)
good = {
    "customer": "Ravi", "address": {"city": "Pune", "pincode": "411001"},
    "items": [{"product": "Pen", "quantity": 3, "unit_price": 20},
              {"product": "Notebook", "quantity": 2, "unit_price": 60}],
    "order_date": "2026-09-27", "delivery_date": "2026-09-30",
}
print(client.post("/orders", json=good).json())

bad = {**good, "address": {"city": "Pune", "pincode": "41"},
       "items": [{"product": "Pen", "quantity": 0, "unit_price": 20}], "coupon": "FREE"}
response = client.post("/orders", json=bad)
print(response.status_code)
for error in response.json()["detail"]:
    print(".".join(str(part) for part in error["loc"]), "->", error["msg"])

# Model validators run only after every field is valid:
dates_only = {**good, "delivery_date": "2026-09-01"}
print(client.post("/orders", json=dates_only).json()["detail"][0]["msg"])
Output
{'customer': 'Ravi', 'city': 'Pune', 'total': 180.0}
422
body.address.pincode -> String should have at least 6 characters
body.items.0.quantity -> Input should be greater than or equal to 1
body.coupon -> Extra inputs are not permitted
Value error, delivery_date must be on or after order_date

Body, path and query parameters together

Python
from typing import Annotated
from fastapi import Body, FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

class Review(BaseModel):
    rating: int
    comment: str = ""

@app.put("/books/{book_id}/reviews/{user}")
def upsert_review(
    book_id: int,                              # path
    user: str,                                 # path
    review: Review,                            # body (a model)
    notify: bool = False,                      # query
    source: Annotated[str, Body()] = "web",    # extra single value read from the body
):
    return {"book_id": book_id, "user": user, "review": review, "notify": notify, "source": source}

client = TestClient(app)
body = {"review": {"rating": 5, "comment": "Clear and practical"}, "source": "mobile"}
print(client.put("/books/7/reviews/asha?notify=true", json=body).json())
Output
{'book_id': 7, 'user': 'asha', 'review': {'rating': 5, 'comment': 'Clear and practical'}, 'notify': True, 'source': 'mobile'}

Common Mistakes

  • Reading request.json() by hand instead of declaring a Pydantic model.
  • Using the creation model for PATCH, which forces clients to resend every field.
  • Calling model_dump() without exclude_unset=True in a PATCH and overwriting data with defaults.
  • Accepting unknown fields silently when typos should be rejected — use extra="forbid" where appropriate.
  • Validating cross-field rules in the endpoint instead of in a model_validator.

Exercise

Define a Book model with a title and a price that must be greater than zero. Add a POST /books endpoint that stores the book and returns it with an id. The second request sends an invalid price.

Expected output: {'id': 1, 'title': 'Dune', 'price': 9.5} then 422

Python · starter code
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()
books = []

# TODO: class Book(BaseModel) with title: str and price: float greater than 0

# TODO: POST /books that appends the book and returns its fields plus an "id"


client = TestClient(app)
print(client.post("/books", json={"title": "Dune", "price": 9.5}).json())
print(client.post("/books", json={"title": "Dune", "price": -1}).status_code)
Show hints
  • A constraint is declared with Field: price: float = Field(gt=0).
  • book.model_dump() returns the model as a dictionary, which can be merged with the id.
Show solution
Python · solution
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()
books = []


class Book(BaseModel):
    title: str
    price: float = Field(gt=0)


@app.post("/books")
def create_book(book: Book):
    books.append(book)
    return {"id": len(books), **book.model_dump()}


client = TestClient(app)
print(client.post("/books", json={"title": "Dune", "price": 9.5}).json())
print(client.post("/books", json={"title": "Dune", "price": -1}).status_code)

Quick quiz

1. How does FastAPI know that a parameter should be read from the JSON body?

  • A. Its type is a Pydantic model
  • B. Its name is body
  • C. It has no default
  • D. It is the first parameter
Show answer

A. Simple types are taken from the path or the query string; models come from the body.

2. Which method converts a Pydantic v2 model to a dictionary?

  • A. to_dict()
  • B. model_dump()
  • C. as_dict()
  • D. json()
Show answer

B. model_dump_json() returns a JSON string instead.

3. What is the difference between PUT and PATCH?

  • A. There is none
  • B. PUT replaces the whole resource; PATCH changes only the fields that are sent
  • C. PATCH creates a resource
  • D. PUT is for deleting
Show answer

B. A PATCH model usually has every field optional.

Interview questions

What is Pydantic and what role does it play in FastAPI?

Show answer

Pydantic is a library that validates and converts data using classes with type hints. A model declares the fields, their types and constraints; creating an instance from raw data either yields a correctly typed object or raises a detailed validation error. FastAPI uses Pydantic models for request bodies and responses, so validation, conversion and the documentation of the data shapes all come from one declaration.

How do you implement a partial update with PATCH?

Show answer

Define a separate model in which every field is optional, with a default of None. In the endpoint, call model_dump(exclude_unset=True) to get only the fields the client actually sent, and apply those to the stored object. This distinguishes a field that was omitted from one deliberately set to null.

Key Points to Remember

  • A parameter typed as a Pydantic model is read from the JSON body and fully validated.
  • Field() adds constraints; field_validator and model_validator add custom rules.
  • Nested models and lists of models describe complex JSON precisely.
  • Errors come back as 422 with the location and message of every problem.
  • PATCH: optional fields + model_dump(exclude_unset=True).

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. A layered FastAPI project with a SQLite database, running in your browser. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering