Level Up Your API Schemas: FastAPI Meets Pydantic#

Installing FastAPI#

You can install FastAPI using pip:

1
pip install fastapi uvicorn

• FastAPI is the main framework.
• Uvicorn is a high-performance ASGI server used to run FastAPI apps.

Creating a Simple App#

Here’s the minimal code for a FastAPI application:

1
from fastapi import FastAPI
2

3
app = FastAPI()
4

5
@app.get("/")
6
def read_root():
7
    return {"message": "Hello, FastAPI!"}

Let’s break it down:

1. Import and Instantiate: You import FastAPI and create an application instance, app = FastAPI().
2. Decorator-based Routing: Decorate a function with @app.get("/"), which means this function responds to HTTP GET requests at the root path /.
3. Return Data: Return any valid Python data structure. FastAPI automatically converts it to JSON.

Running the App#

Spin up the server with:

1
uvicorn main:app --reload

You can toggle the --reload flag for automatic reloading during development. Once it’s running, navigate to http://localhost:8000.

Creating Your First Model#

A basic Pydantic model might look like this:

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    name: str

• You subclass BaseModel.
• You specify attributes with type hints (e.g., id: int, name: str).
• Pydantic automatically provides validation and serialization.

Instantiating Models#

1
user_data = {"id": 1, "name": "Alice"}
2
user = User(**user_data)
3
print(user)  # id=1 name='Alice'
4
print(user.dict())  # {'id': 1, 'name': 'Alice'}

By passing **user_data, we initialize the fields of the model with the provided dictionary. If user_data is missing required fields or if invalid types are passed (e.g., strings for an integer field), Pydantic will raise a ValidationError.

Model Methods#

Some helpful Pydantic model methods:

• dict(): returns a dictionary of the model’s data.
• json(): returns a JSON string.
• copy(): creates a (shallow or deep) copy of the model, optionally updating fields.

Defining an Endpoint with a Pydantic Model#

1
from fastapi import FastAPI
2
from pydantic import BaseModel
3

4
app = FastAPI()
5

6
class User(BaseModel):
7
    id: int
8
    name: str
9

10
@app.post("/users/")
11
def create_user(user: User):
12
    return {"message": f"User {user.name} created!", "user_id": user.id}

1. Request Body Parsing: FastAPI automatically parses the request body according to the User model.
2. Validation: If the incoming JSON doesn’t meet User constraints, a 422 Unprocessable Entity error is returned, complete with a JSON error message.
3. Interactive Docs: Navigate to http://localhost:8000/docs to test out the API. The required JSON schema for the request body will be generated automatically.

Query Parameters with Pydantic#

You can use Pydantic models to handle more complex query parameters. Although single or simple query parameters might be defined directly, for multi-parameter or complex structures, consider using a Pydantic model.

1
from pydantic import BaseModel
2
from typing import Optional
3

4
class FilterParams(BaseModel):
5
    sort_by: Optional[str] = None
6
    limit: int = 10
7
    offset: int = 0
8

9
@app.get("/items/")
10
def list_items(params: FilterParams = Depends()):
11
    """
12
    By using Depends(), we tell FastAPI to create a
13
    FilterParams object from query parameters.
14
    """
15
    return {
16
        "sort_by": params.sort_by,
17
        "limit": params.limit,
18
        "offset": params.offset
19
    }

When you make a GET request like:
GET /items/?sort_by=price&limit=5&offset=10,
the params object will be populated with the corresponding values.

Built-in Constraints#

You can use Pydantic’s built-in field constraints:

1
from pydantic import BaseModel, conint, constr
2

3
class Product(BaseModel):
4
    name: constr(min_length=1, max_length=100)
5
    price: conint(gt=0)

• constr ensures name is at least 1 character and at most 100 characters.
• conint(gt=0) ensures price is an integer greater than 0.

Custom Validators#

For more advanced validation logic, define a method with the @validator decorator:

1
from pydantic import BaseModel, validator
2

3
class Order(BaseModel):
4
    quantity: int
5
    price_per_item: float
6

7
    @validator("quantity")
8
    def check_quantity_positive(cls, v):
9
        if v <= 0:
10
            raise ValueError("Quantity must be greater than zero.")
11
        return v
12

13
    @validator("price_per_item")
14
    def check_price_positive(cls, v):
15
        if v <= 0:
16
            raise ValueError("Price per item must be greater than zero.")
17
        return v

If invalid data is provided, FastAPI surfaces these validation errors in the response body with a 422 Unprocessable Entity status code. The error explains which field(s) failed and why.

Example of Nested Models#

1
from typing import List
2
from pydantic import BaseModel
3

4
class Address(BaseModel):
5
    street: str
6
    city: str
7
    country: str = "USA"
8

9
class User(BaseModel):
10
    id: int
11
    name: str
12
    addresses: List[Address]
13

14
@app.post("/users/")
15
def create_user(user: User):
16
    # user.addresses[0].city will be available, for instance.
17
    return {"user_info": user.dict()}

When you send a JSON payload like:

1
{
2
  "id": 1,
3
  "name": "Alice",
4
  "addresses": [
5
    {"street": "123 Main St", "city": "Springfield", "country": "USA"},
6
    {"street": "456 Elm St", "city": "Shelbyville"}
7
  ]
8
}

Pydantic seamlessly converts these nested dictionaries into Address and User objects. Each nested model is validated according to its own schema. If anything is invalid (e.g., missing required keys, incorrect data types), FastAPI returns a validation error.

Model Config#

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    full_name: str
6

7
    class Config:
8
        # Example config options
9
        title = "User Schema"
10
        anystr_strip_whitespace = True
11
        validate_assignment = True

1. title: Used to provide a title in JSON Schema generation.
2. anystr_strip_whitespace: Strips leading/trailing whitespace from strings.
3. validate_assignment: Forces re-validation of fields upon assignment to an existing model.

Field Alias and Computed Fields#

You might want to rename fields in your JSON but keep Pythonic naming in your code. That’s where aliases come in:

1
from pydantic import BaseModel, Field
2

3
class User(BaseModel):
4
    user_id: int = Field(..., alias="id")
5
    full_name: str = Field(..., alias="fullName")
6

7
    class Config:
8
        allow_population_by_field_name = True

• Field(..., alias="id") ensures that JSON with the key "id" maps to the attribute user_id in Python.
• allow_population_by_field_name allows you to pass user_id as a keyword argument in Python if desired, while JSON drops it under "id".

Environment and Settings#

For larger applications, consider using Pydantic’s Settings management to manage environment variables, secret keys, etc.:

1
from pydantic import BaseSettings
2

3
class AppSettings(BaseSettings):
4
    api_key: str
5
    debug_mode: bool = False
6

7
    class Config:
8
        env_file = ".env"
9

10
settings = AppSettings()

• You can populate AppSettings from your operating system environment or a .env file.
• This approach makes configuring deployments simpler: just set environment variables, and Pydantic handles the rest.

Custom Field Types and Encoders#

What if your model needs a custom type (like a URL, an email address, or a domain-specific data type)? You can define custom types or leverage Pydantic’s built-in types:

1
from pydantic import BaseModel, HttpUrl, EmailStr
2

3
class Contact(BaseModel):
4
    email: EmailStr
5
    website: HttpUrl
6

7
    # For domain-specific types, you can also create a custom validator.

• EmailStr ensures a field is a valid email.
• HttpUrl ensures the field is a valid URL.

You can also define custom encoders if you have types that aren’t JSON serializable by default (like datetime objects, UUID, etc.). Pydantic automatically handles some of them, but you can override or extend that process by updating your model’s json_encoders in Config.

1
import datetime
2

3
class MyModel(BaseModel):
4
    timestamp: datetime.datetime
5

6
    class Config:
7
        json_encoders = {
8
            datetime.datetime: lambda v: v.isoformat()
9
        }

Performance Considerations#

Although FastAPI is already quite efficient, you can further optimize:

1. Re-use Pydantic models: Instead of creating new models for each endpoint variation, consider re-usable models with optional fields.
2. Pre-compile your schema: For extremely high traffic APIs, pre-compiling the JSON schema can cut overhead. However, this is usually an edge case optimization.
3. Limit advanced validations: Each custom validation or complex logic can slow down the request handling. Only implement advanced logic when absolutely necessary.

Custom Error Handling#

By default, FastAPI returns a detailed JSON response for validation errors. If you need to customize this behavior (for example, to format errors differently or add error codes), you can write custom exception handlers:

1
from fastapi import FastAPI, Request
2
from fastapi.responses import JSONResponse
3
from pydantic import ValidationError
4

5
app = FastAPI()
6

7
@app.exception_handler(ValidationError)
8
async def validation_exception_handler(request: Request, exc: ValidationError):
9
    return JSONResponse(
10
        status_code=422,
11
        content={
12
            "custom_error": True,
13
            "errors": exc.errors(),
14
        }
15
    )

When a ValidationError occurs, your custom handler intercepts it and returns a structured response. This approach is especially useful if you need to maintain a specific error format for client-side consumption.

Multiple Models in One Endpoint#

Sometimes you need to accept multiple models in one request. Perhaps you’re receiving a query param model and a request body model in the same endpoint:

1
from fastapi import Body, Query
2

3
class QueryParams(BaseModel):
4
    page: int = 1
5
    size: int = 10
6

7
class Payload(BaseModel):
8
    data: str
9

10
@app.post("/process/")
11
def process_data(
12
    query: QueryParams = Depends(),
13
    payload: Payload = Body(...)
14
):
15
    return {
16
        "page": query.page,
17
        "size": query.size,
18
        "data": payload.data
19
    }

This approach is quite flexible and ensures each type of data is cleanly separated and validated.

Conditional Fields and Logic#

Pydantic’s root_validator can handle validation that spans multiple fields or the entire model:

1
from pydantic import BaseModel, root_validator
2

3
class Payment(BaseModel):
4
    card_number: str = None
5
    paypal_id: str = None
6

7
    @root_validator
8
    def check_card_or_paypal(cls, values):
9
        card_number = values.get('card_number')
10
        paypal_id = values.get('paypal_id')
11
        if not card_number and not paypal_id:
12
            raise ValueError("Either card_number or paypal_id must be provided.")
13
        return values

This ensures the presence of at least one payment method, but not necessarily both.

Handling Large File Uploads#

FastAPI integrates well with Pydantic for metadata, though file uploads themselves are not strictly validated by Pydantic (since they come in as form-data). However, you can combine both:

1
from fastapi import FastAPI, UploadFile, File
2
from pydantic import BaseModel
3

4
class FileMetadata(BaseModel):
5
    description: str
6

7
@app.post("/upload/")
8
async def upload_file(file: UploadFile = File(...), metadata: FileMetadata = None):
9
    content = await file.read()
10
    return {
11
        "filename": file.filename,
12
        "description": metadata.description if metadata else None,
13
        "size": len(content)
14
    }

Background Tasks and Async Features#

FastAPI supports asynchronous request handling. You might also schedule background tasks using BackgroundTasks:

1
from fastapi import BackgroundTasks
2

3
def save_file(file_data: bytes, filename: str):
4
    with open(filename, "wb") as f:
5
        f.write(file_data)
6

7
@app.post("/save/")
8
async def save_endpoint(file: UploadFile, background_tasks: BackgroundTasks):
9
    content = await file.read()
10
    background_tasks.add_task(save_file, content, file.filename)
11
    return {"detail": "File will be saved in the background."}

Pydantic can still validate the request body if you think you might send additional metadata alongside the file.

Integrating with Databases#

While not Pydantic-specific, a typical pattern is to map Pydantic models to your database schema. For instance, you can have a Pydantic UserIn model for incoming data, a UserDB model for data in the database, and a UserOut model for data returned by the API.

1
class UserIn(BaseModel):
2
    email: EmailStr
3
    password: str
4

5
class UserOut(BaseModel):
6
    id: int
7
    email: EmailStr
8

9
class UserDB(UserIn):
10
    id: int
11
    hashed_password: str
12

13
@app.post("/users/", response_model=UserOut)
14
def create_user(user_in: UserIn):
15
    hashed_pw = do_some_hashing(user_in.password)
16
    user_db = UserDB(id=generate_id(), email=user_in.email, password=user_in.password, hashed_password=hashed_pw)
17
    # Save user_db to the database...
18
    return UserOut(id=user_db.id, email=user_db.email)

Setting response_model in the route decorator instructs FastAPI to serialize the returned data as UserOut. That way, you don’t mistakenly leak fields like hashed_password.

Dependency Injection Patterns#

FastAPI’s dependency injection system allows you to define “global” or specialized dependencies that can operate Pydantic models. For example, if you need to fetch the current user from a token:

1
from fastapi import Depends, HTTPException
2
from typing import Optional
3

4
class TokenData(BaseModel):
5
    user_id: Optional[int] = None
6

7
def get_current_user(token: str = Depends(oauth2_scheme)):
8
    # decode token, get user_id
9
    user_id = decode_token(token)
10
    if not user_id:
11
        raise HTTPException(status_code=401, detail="Invalid token")
12
    return user_id
13

14
@app.get("/profile/")
15
def read_profile(user_id: int = Depends(get_current_user)):
16
    # fetch user from DB, etc.
17
    return {"id": user_id, "name": "Alice"}

This approach keeps your business logic modular and testable.

Thorough Testing#

Well-structured Pydantic models make tests more reliable. Test your validations directly:

1
import pytest
2
from pydantic import ValidationError
3

4
def test_user_model():
5
    from app.models import User
6
    data = {"id": "invalid_id", "name": "Alice"}
7
    with pytest.raises(ValidationError):
8
        User(**data)

And test your FastAPI endpoints using the TestClient:

1
from fastapi.testclient import TestClient
2
from main import app
3

4
client = TestClient(app)
5

6
def test_create_user():
7
    response = client.post("/users/", json={"id": 1, "name": "Bob"})
8
    assert response.status_code == 200
9
    assert response.json()["message"] == "User Bob created!"