Validate FastAPI Requests and Responses with Pydantic

How to Validate FastAPI Requests and Responses with Pydantic

In this tutorial, you will learn how to leverage Pydantic schemas to add robust data validation to your FastAPI API. We will cover defining request and response models, implementing field-level constraints, updating existing endpoints to use these models, and creating new endpoints for data creation. By the end, your API documentation will be significantly improved, and your API will be more resilient against invalid data.

What is Pydantic?

Pydantic is a powerful Python library for data validation that uses Python type hints. Unlike standard Python type hints, which are primarily for documentation and static analysis, Pydantic enforces these type hints at runtime. This means Pydantic actively checks your data against the defined types and constraints, providing detailed error messages when validation fails. FastAPI comes with Pydantic pre-installed as a dependency, so no additional installation is required.

Why Use Pydantic with FastAPI?

FastAPI’s core strength lies in its seamless integration with Pydantic. These schemas serve as the contract for your API, defining precisely what data clients can send (requests) and what data your API will return (responses). This separation of concerns is crucial: Pydantic handles data structure and validation, while the database (covered in the next tutorial) manages data persistence. This approach offers several advantages over traditional validation methods:

• Pythonic Approach: Uses familiar Python type hints.
• Automatic Documentation: Generates interactive API documentation (like Swagger UI) showcasing your data models and validation rules.
• Improved IDE Support: Provides better autocompletion and code insights within your Integrated Development Environment (IDE).
• Runtime Validation: Ensures data integrity before it even reaches your application logic.

Prerequisites

• A basic understanding of Python.
• A FastAPI project set up with at least one GET endpoint (as established in previous tutorials).
• Your FastAPI development server running.

Step 1: Create Schema Files

First, we’ll create a dedicated file for our Pydantic schemas. This helps keep our project organized. Create a new file named schemas.py in your project’s root directory.

Import Necessary Components

Inside schemas.py, import the required components from Pydantic:

from pydantic import BaseModel, Field, ConfigDict

Let’s break down these imports:

• BaseModel: The base class from which all Pydantic models inherit.
• Field: Used to add validation constraints (like minimum/maximum length) to model fields.
• ConfigDict: The modern Pydantic v2 way to configure models (replacing the older Config class).

Define a Base Schema for Shared Fields

To avoid repetition (DRY principle), we’ll create a base schema that includes fields common to both creating and returning posts. This schema will define the core attributes of a post: title, content, and author.

class PostBase(BaseModel):
    title: str
    content: str
    author: str

While this looks similar to a Python dataclass, Pydantic uses these type hints for runtime validation.

Add Field Constraints

Currently, these fields accept any string, including empty ones. Let’s add constraints using Field:

class PostBase(BaseModel):
    title: str = Field(min_length=1, max_length=100)
    content: str = Field(min_length=1)
    author: str = Field(min_length=1, max_length=50)

Note: By not providing default values for these fields, Pydantic makes them required. If a required field is missing, validation will fail.

Create a Schema for Post Creation

This schema defines the data structure expected when a client creates a new post. It will inherit from PostBase.

class PostCreate(PostBase):
    pass

For now, PostCreate is identical to PostBase. However, defining it separately clearly indicates its purpose and allows for future flexibility. For instance, if user authentication is added later, the author field might be omitted here as it could be inferred from the logged-in user.

Create a Schema for Post Responses

This schema defines the structure of the data returned by your API when retrieving posts. It will also inherit from PostBase and include additional fields generated by the server, such as an ID and the date posted.

class PostResponse(PostBase):
    id: int
    date_posted: str

    model_config = ConfigDict(from_attributes=True)

Explanation of model_config:

• In Pydantic v2, configuration is done using ConfigDict.
• from_attributes=True tells Pydantic that it can read data from objects with attributes (like database models) in addition to dictionaries. This is crucial for when we integrate a database in the next tutorial, as database query results are often accessed via attributes (e.g., post.title) rather than dictionary keys (e.g., post['title']). Without this, Pydantic would fail to read data from database objects.

Note on id field: While it’s generally advisable to avoid naming fields id due to it being a Python built-in, it’s a standard convention for database models and API responses. Within a class scope, it doesn’t conflict with the global function and won’t trigger linter warnings.

Note on date_posted: Currently, date_posted is a string because our in-memory data uses strings for dates. This will be changed to a proper datetime object when we introduce the database.

Step 2: Update Main API File

Now, let’s integrate these schemas into your main FastAPI application file (e.g., main.py).

Import Schemas

At the top of your main.py file, import the necessary schemas:

from schemas import PostCreate, PostResponse

We don’t need to import PostBase directly into main.py as it’s just a base class for inheritance.

Update GET Endpoints

Modify your existing GET endpoints to use the PostResponse model. This tells FastAPI what structure to expect for responses and improves documentation.

Get All Posts Endpoint

For the endpoint that returns a list of all posts, add the response_model parameter:

@app.get("/api/posts", response_model=list[PostResponse])
def get_posts():
    return posts

Benefit: FastAPI will now validate that each item in the returned list conforms to the PostResponse schema. Any extra fields not defined in PostResponse will be filtered out, and missing required fields will raise an error. This acts as a safeguard against accidentally exposing sensitive data.

Get Single Post Endpoint

Similarly, update the endpoint for retrieving a single post:

@app.get("/api/posts/{post_id}", response_model=PostResponse)
def get_post(post_id: int):
    for post in posts:
        if post["id"] == post_id:
            return post
    raise HTTPException(status_code=404, detail="Post not found")

Here, we specify that the response should be a single PostResponse object.

Step 3: Create a POST Endpoint for New Posts

Now, let’s add an endpoint to create new posts. This is where Pydantic’s request validation truly shines.

from fastapi import HTTPException

# ... (previous code)

@app.post("/api/posts", response_model=PostResponse, status_code=201)
def create_post(post: PostCreate):
    # Manually generate ID for in-memory data (will be replaced by DB later)
    new_id = max([p['id'] for p in posts], default=0) + 1

    new_post_data = {
        "id": new_id,
        "title": post.title,
        "content": post.content,
        "author": post.author,
        "date_posted": "2023-01-01T12:00:00Z" # Hardcoded for now
    }
    posts.append(new_post_data)
    return new_post_data

Key aspects of this endpoint:

• @app.post: Indicates this is an HTTP POST request, typically used for creating resources.
• response_model=PostResponse: Specifies the structure of the successful response.
• status_code=201: Sets the default success status code to 201 Created, a RESTful best practice for resource creation.
• post: PostCreate: This is the core of Pydantic integration for requests. FastAPI automatically:
• Parses the JSON request body.
• Validates the data against the PostCreate schema.
• Returns a 422 Unprocessable Entity error with detailed messages if validation fails, *before* your function logic is executed.
• Function Logic: If the data is valid, the function proceeds. We manually generate a new ID (this will be handled by the database later), construct a dictionary including the validated data and generated fields, append it to our in-memory posts list, and return the newly created post.

Step 4: Test in Interactive Docs

With the changes made, restart your FastAPI development server and navigate to your interactive API documentation (usually at http://127.0.0.1:8000/docs).

Observe Improved Documentation

You’ll notice significant improvements:

• GET Endpoints: The Response section for /api/posts and /api/posts/{post_id} now clearly displays the structure of the PostResponse schema, including fields, types, and constraints.
• POST Endpoint: The new POST /api/posts endpoint is visible. The Request body section shows the expected fields (title, content, author) and their types. Clicking on the Schema link provides detailed validation rules (e.g., minimum and maximum lengths).

Test Data Creation

1. Go to the POST /api/posts endpoint.
2. Click Try it out.
3. Fill in the title, content, and author fields.
4. Click Execute.

You should receive a 201 Created response, containing the newly created post with its generated ID and date. The new post will also appear if you call the GET /api/posts endpoint.

Test Validation Errors

To test Pydantic’s validation:

• Missing Required Field: Try creating a post without providing the author field. You should receive a 422 Unprocessable Entity error indicating that the author field is required.
• Constraint Violation: Try creating a post with a title that is too short (less than 1 character) or too long (more than 100 characters). You’ll get a 422 error detailing the specific constraint violation (e.g., “String should have at least 1 character”).

These validation errors are generated automatically by Pydantic, saving you from writing manual `if` statements or `try-except` blocks.

Understanding Data Persistence (and the Need for a Database)

You might notice that any posts created through the API disappear when you restart the development server. This is because our posts data is stored in a simple Python list in memory. When the server restarts, this list is re-initialized with only the hard-coded initial posts.

For real-world applications, data must persist across server restarts. This is where a database comes in. In the next tutorial, we will integrate a database (like SQL Alchemy) to provide persistent storage for your posts.

Summary

In this tutorial, we:

• Created a schemas.py file to house our Pydantic models.
• Defined PostBase for shared fields, PostCreate for request data, and PostResponse for response data.
• Implemented field-level validation using Field for constraints like min_length and max_length.
• Updated our GET endpoints to use response_model for better documentation and data safety.
• Created a POST endpoint that leverages Pydantic for automatic request validation.
• Tested our API using the interactive documentation, verifying both successful operations and validation error handling.

Pydantic schemas act as the contract for your API, defining what data goes in and what comes out. FastAPI utilizes these schemas for validation, serialization, and documentation, creating an elegant and efficient development workflow. The concepts learned here will be foundational for integrating a database in the next tutorial.

---

Source: Python FastAPI Tutorial (Part 4): Pydantic Schemas – Request and Response Validation (YouTube)