FastAPI Best Practices

Create a global CustomModel inheriting from BaseModel to enforce application-wide standards. Common use cases include:

• Standardizing datetime serialization (e.g., forcing UTC and specific string formats) using @field_serializer.
• Adding utility methods like serializable_dict() to return dictionaries containing only JSON-serializable fields using jsonable_encoder.

from datetime import datetime
from typing import Any
from zoneinfo import ZoneInfo
from fastapi.encoders import jsonable_encoder
from pydantic import BaseModel, ConfigDict, field_serializer

class CustomModel(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    @field_serializer("*", when_used="json", check_fields=False)
    def _serialize_datetimes(self, value: Any) -> Any:
        if isinstance(value, datetime):
            if value.tzinfo is None:
                value = value.replace(tzinfo=ZoneInfo("UTC"))
            return value.strftime("%Y-%m-%dT%H:%M:%S%z")
        return value

    def serializable_dict(self, **kwargs):
        """Returns a dictionary containing only serializable fields."""
        default_dict = self.model_dump()
        return jsonable_encoder(default_dict)

FastAPI handles async and sync routes differently. Choosing the wrong one for I/O operations can block your entire server.

Guidelines for I/O (DB calls, API requests, File I/O):

1. Use async def with non-blocking calls: This is the most efficient method. Use await with asynchronous libraries (e.g., asyncio.sleep(), httpx, motor). The event loop remains free to handle other requests.
2. Use def (sync) for blocking calls: If you must use a synchronous library that blocks (e.g., time.sleep(), requests), define the route with def instead of async def. FastAPI will automatically run these in a separate threadpool, preventing the main event loop from being blocked.
3. Avoid async def with blocking calls: Never use time.sleep() or synchronous I/O inside an async def function. This blocks the entire event loop, meaning the server cannot accept any new requests until the operation finishes.

Comparison Summary:

import asyncio
import time
from fastapi import APIRouter

router = APIRouter()

# BAD: Blocks the entire event loop
@router.get("/terrible-ping")
async def terrible_ping():
    time.sleep(10) 
    return {"pong": True}

# GOOD: Runs in a separate threadpool
@router.get("/good-ping")
def good_ping():
    time.sleep(10) 
    return {"pong": True}

# PERFECT: Non-blocking awaitable
@router.get("/perfect-ping")
async def perfect_ping():
    await asyncio.sleep(10) 
    return {"pong": True}

Dependencies can depend on other dependencies, allowing you to build complex validation logic from simple, reusable building blocks.

Key Benefit: Caching. FastAPI caches the result of a dependency within a single request's scope. If multiple dependencies in a single route call the same underlying dependency (e.g., parse_jwt_data), that dependency is executed only once.

# dependencies.py
async def parse_jwt_data(token: str = Depends(OAuth2PasswordBearer(tokenUrl="/auth/token"))) -> dict:
    # ... logic to decode JWT
    return {"user_id": payload["id"]}

async def valid_owned_post(
    post: Mapping = Depends(valid_post_id), 
    token_data: dict = Depends(parse_jwt_data),
) -> Mapping:
    if post["creator_id"] != token_data["user_id"]:
        raise UserNotOwner()
    return post

# router.py
@router.get("/users/{user_id}/posts/{post_id}")
async def get_user_post(
    post: Mapping = Depends(valid_owned_post),
    user: Mapping = Depends(valid_active_creator),
):
    # parse_jwt_data is called only once here, even though used by both dependencies
    return post

FastAPI's BackgroundTasks runs tasks after the response is sent, in the same worker process. Use it only for short, non-critical tasks where failure can be silently dropped. For anything else, use a dedicated task queue like Celery, Arq, or RQ.

from fastapi import BackgroundTasks

@router.post("/signup")
async def signup(data: SignupIn, bg: BackgroundTasks):
    user = await service.create_user(data)
    # Use for fire-and-forget, in-process tasks
    bg.add_task(send_welcome_email, user.email) 
    return user

FastAPI handles synchronous and asynchronous routes differently. Choosing the right one is critical for performance:

1. async def (The Perfect Way): Use this for non-blocking I/O operations (e.g., using await asyncio.sleep() or an async database driver). This allows the event loop to process other requests while waiting.
2. def (The Safe Way for Sync I/O): If you must use a blocking synchronous library (e.g., time.sleep() or a synchronous SDK), define the route with def instead of async def. FastAPI will run these in a separate thread pool, preventing the main event loop from being blocked.
3. async def with Blocking Code (The Terrible Way): Never perform blocking I/O (like time.sleep()) inside an async def route. This will block the entire event loop, preventing the server from handling any other incoming requests until the operation completes.

Summary Table:

import asyncio
import time
from fastapi import APIRouter

router = APIRouter()

# BAD: Blocks the entire process
@router.get("/terrible-ping")
async def terrible_ping():
    time.sleep(10)
    return {"pong": True}

# GOOD: Runs in a separate thread pool
@router.get("/good-ping")
def good_ping():
    time.sleep(10)
    return {"pong": True}

# PERFECT: Non-blocking I/O
@router.get("/perfect-ping")
async def perfect_ping():
    await asyncio.sleep(10)
    return {"pong": True}

To maximize dependency reuse across different routes, use consistent variable names in your path parameters. For example, if multiple endpoints validate a profile, use {profile_id} in all of them. This allows you to chain dependencies: a valid_creator_id dependency can depend on a valid_profile_id dependency.

# src.profiles.dependencies
async def valid_profile_id(profile_id: UUID4) -> Mapping:
    profile = await service.get_by_id(profile_id)
    if not profile:
        raise ProfileNotFound()
    return profile

# src.creators.dependencies
async def valid_creator_id(profile: Mapping = Depends(valid_profile_id)) -> Mapping:
    if not profile["is_creator"]:
       raise ProfileNotCreator()
    return profile

# src.creators.router.py
@router.get("/creators/{profile_id}", response_model=ProfileResponse)
async def get_user_profile_by_id(creator_profile: Mapping = Depends(valid_creator_id)):
    return creator_profile