Skip to main content

Request and Response Bodies: Pydantic models

Following our lesson on API Routing and HTTP Verbs for RESTful Endpoints, this article focuses on Request and Response Bodies: Pydantic models. Pydantic is a library for data validation and settings management using Python type hints. FastAPI uses Pydantic models to define the structure of request and response bodies, providing automatic validation and serialization.

📚 Prerequisites​

  • A running FastAPI application.
  • Understanding of Python type hints.

🎯 Article Outline: What You'll Master​

  • ✅ Creating Pydantic Models: Defining the structure of your data.
  • ✅ Request Bodies: Using Pydantic models to validate incoming data.
  • ✅ Response Models: Using Pydantic models to format outgoing data.
  • ✅ Data Conversion: How FastAPI automatically converts data to and from JSON.

🧠 Section 1: The Core Concepts of Pydantic Models​

Pydantic models (also called "schemas") are classes that inherit from pydantic.BaseModel. You define the fields of the model as class attributes with type hints. Pydantic then uses these type hints to validate data and to serialize and deserialize data to and from JSON.

💻 Section 2: Deep Dive - Implementation and Walkthrough​

Let's refactor our item "database" to use Pydantic models.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Optional

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

@app.put("/items/{item_id}", response_model=Item)
async def update_item(item_id: int, item: Item):
    # In a real app, you would fetch and update the item in a database
    return item

Step-by-Step Code Breakdown:

  1. class Item(BaseModel):: We define an Item model with fields name, description, price, and tax.
  2. create_item(item: Item): We type-hint the item parameter as our Item model. FastAPI will automatically parse the JSON request body, validate it against the Item model, and pass an instance of Item to our function.
  3. response_model=Item: In the update_item route, we use the response_model argument in the decorator. This tells FastAPI to serialize the return value to JSON using our Item model. This is useful for ensuring the response conforms to a specific schema.

💡 Conclusion & Key Takeaways​

You've learned how to use Pydantic models in FastAPI to define and validate the data in your request and response bodies. This is a cornerstone of building robust and reliable APIs with FastAPI.

Let's summarize the key takeaways:

  • Pydantic models are used to define data schemas.
  • FastAPI uses these models to automatically validate request bodies and serialize response bodies.
  • This provides a powerful and easy-to-use way to ensure data consistency.

➡️ Next Steps​

In the next article, "Status Codes and Error Handling in Web APIs", we'll learn how to return appropriate HTTP status codes and handle errors gracefully.

Glossary​

  • Pydantic: A data validation and settings management library for Python.
  • Schema: A definition of the structure of data.
  • Serialization: The process of converting a data structure or object into a format that can be stored or transmitted.
  • Deserialization: The process of converting a stored or transmitted format back into a data structure or object.

Further Reading​