Building APIs with FastAPI + Pydantic

When clients send invalid data to your API, FastAPI automatically validates it against your Pydantic models and returns a validation error response. By default, this response is a 422 Unprocessable Entity with detailed error information:

python
{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "name"],
      "msg": "Input should be a valid string",
      "input": 123
    }
  ]
}

This automatic behavior is great, but sometimes you want to customize the error response for better user experience. You can override the default validation error handler:

python
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from pydantic import ValidationError

app = FastAPI()

@app.exception_handler(ValidationError)
async def validation_exception_handler(request: Request, exc: ValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": "Validation failed", "details": exc.errors()}
    )

You can also add a custom error response example to your OpenAPI documentation:

python
@app.post("/items", 
    responses={422: {"description": "Validation error"}})
def create_item(item: Item):
    return item

Beyond validation errors, your API needs to handle application-specific errors like "item not found" or "insufficient permissions". FastAPI provides HTTPException for this:

python
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id == 999:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"id": item_id}

You can also create custom exception classes and register handlers:

python
class ItemNotFound(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFound)
async def item_not_found_handler(request: Request, exc: ItemNotFound):
    return JSONResponse(
        status_code=404,
        content={"error": f"Item {exc.item_id} not found"}
    )

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id == 999:
        raise ItemNotFound(item_id)
    return {"id": item_id}

This lets you:

1. Throw specific exceptions in your business logic
2. Handle them consistently across all endpoints
3. Return proper HTTP status codes and error messages

In production, you need to track what requests come in, how long they take, and what errors occur. FastAPI middleware lets you log requests and responses:

python
import logging
from fastapi import FastAPI, Request
import time

app = FastAPI()
logger = logging.getLogger(__name__)

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    
    logger.info(f"{request.method} {request.url.path} - {response.status_code} - {process_time:.3f}s")
    return response

This middleware:

1. Records the start time
2. Calls the next middleware/endpoint
3. Calculates processing time
4. Logs the request details
5. Returns the response

You can also log request bodies for debugging (but be careful with sensitive data):

python
@app.middleware("http")
async def log_body(request: Request, call_next):
    body = await request.body()
    logger.debug(f"Request body: {body}")
    response = await call_next(request)
    return response

For production, use structured logging with tools like loguru or python-json-logger to make logs machine-readable.

Now it's time to build a complete REST API that combines everything: routing, request validation, response models, error handling, and logging.

A full CRUD (Create, Read, Update, Delete) API looks like this:

python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    price: float

class ItemCreate(BaseModel):
    name: str
    price: float

items_db = []

@app.post("/items", status_code=201, response_model=Item)
def create_item(item: ItemCreate):
    new_item = {"id": len(items_db) + 1, "name": item.name, "price": item.price}
    items_db.append(new_item)
    return new_item

@app.get("/items", response_model=List[Item])
def list_items():
    return items_db

@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
    for item in items_db:
        if item["id"] == item_id:
            return item
    raise HTTPException(status_code=404, detail="Item not found")

@app.put("/items/{item_id}", response_model=Item)
def update_item(item_id: int, item: ItemCreate):
    for existing_item in items_db:
        if existing_item["id"] == item_id:
            existing_item["name"] = item.name
            existing_item["price"] = item.price
            return existing_item
    raise HTTPException(status_code=404, detail="Item not found")

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    for i, item in enumerate(items_db):
        if item["id"] == item_id:
            items_db.pop(i)
            return {"message": "Item deleted"}
    raise HTTPException(status_code=404, detail="Item not found")

This API supports:

• POST to create items
• GET to list or retrieve items
• PUT to update items
• DELETE to remove items
• Proper error handling with HTTPException
• Request/response validation with Pydantic

FastAPI is a modern Python web framework for building APIs. It uses type hints and Pydantic models to automatically validate incoming data and generate API documentation.

A minimal FastAPI app looks like this:

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

When you run this app with uvicorn main:app --reload, FastAPI:

1. Creates an HTTP server
2. Routes requests to the correct handler function
3. Automatically validates the response and converts it to JSON
4. Generates interactive OpenAPI documentation at /docs

Each route decorator (@app.get, @app.post, etc.) maps an HTTP method and path to a Python function. The return value is automatically converted to JSON and sent to the client.

Path parameters are parts of the URL that change based on the resource being requested. In FastAPI, you define them using curly braces in the route and add them as function parameters:

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

When a client requests /users/42, FastAPI:

1. Extracts 42 from the URL
2. Validates that it's an integer (due to the type hint)
3. Passes it to the function as user_id=42
4. Returns the response as JSON

If the client requests /users/abc, FastAPI returns a validation error because abc cannot be converted to an integer. The type hint acts as a validator!

You can use multiple path parameters in a single route:

python
@app.get("/posts/{post_id}/comments/{comment_id}")
def get_comment(post_id: int, comment_id: int):
    return {"post_id": post_id, "comment_id": comment_id}

Query parameters are optional or required values that appear after the ? in a URL. For example, in /items?skip=0&limit=10, skip and limit are query parameters.

In FastAPI, you define query parameters by adding them to the function signature without including them in the route path:

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def get_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

When a client requests /items?skip=5&limit=20, the values are automatically parsed and validated:

• skip becomes 5
• limit becomes 20

If the client requests /items without parameters, the defaults apply:

• skip becomes 0
• limit becomes 10

You can also mix path parameters and query parameters:

python
@app.get("/users/{user_id}/posts")
def get_user_posts(user_id: int, skip: int = 0, limit: int = 10):
    return {"user_id": user_id, "skip": skip, "limit": limit}

Here, user_id is a required path parameter, and skip/limit are optional query parameters with defaults.

Path and query parameters work for small amounts of data, but when clients need to send complex structured data (like creating a new user or posting content), you use request bodies. FastAPI integrates seamlessly with Pydantic models to validate request bodies.

python
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float

@app.post("/items")
def create_item(item: Item):
    return {"item": item, "status": "created"}

When a client sends a POST request with a JSON body:

python
{"name": "Widget", "description": "A useful widget", "price": 19.99}

FastAPI:

1. Reads the JSON from the request body
2. Validates it against the Item model
3. Converts it to an Item instance
4. Passes it to the function

If the client sends invalid data (wrong types, missing fields), FastAPI automatically returns a validation error response. You never need to manually parse JSON or validate types!

A well-designed API separates the request input model from internal database models. This gives you flexibility to validate input separately from how data is stored.

Consider an endpoint that creates a user. The request might accept a password, but the database stores only a password hash. The response might return created_at but not the password:

python
from pydantic import BaseModel, EmailStr, Field
from typing import Optional

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=8)
    full_name: Optional[str] = None

class UserInDB(BaseModel):
    id: int
    username: str
    email: str
    password_hash: str
    full_name: Optional[str]
    created_at: str

class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    full_name: Optional[str]
    created_at: str

In the endpoint, you accept UserCreate (from the client), use it to create a UserInDB (for storage), and return UserResponse (without sensitive data).

Using Field() constraints in request models ensures data quality at the API boundary:

• min_length/max_length for strings
• gt/lt for numeric comparisons
• regex patterns for format validation

Response models control exactly what data your API returns to clients. They also generate the OpenAPI documentation that describes your API.

You tell FastAPI which model to use for the response using the response_model parameter:

python
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    id: int
    name: str
    price: float

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float
    on_sale: bool = False

@app.get("/items/{item_id}", response_model=ItemResponse)
def get_item(item_id: int):
    return {"id": item_id, "name": "Widget", "price": 19.99}

Benefits of explicit response models:

1. Documentation: OpenAPI shows clients exactly what fields are returned
2. Validation: FastAPI validates that your function returns the correct structure
3. Exclusion: You can exclude sensitive fields that shouldn't be returned
4. Transformation: Response models can compute or transform data

You can also exclude fields dynamically:

python
@app.get("/items", response_model=List[ItemResponse])
def list_items():
    return [{"id": 1, "name": "Item 1", "price": 10.0}]

Real-world APIs often return nested structures where one entity contains others. For example, a blog post includes comments, and each comment includes user information.

In Pydantic, you create nested models by using other models as field types:

python
from pydantic import BaseModel
from typing import List

class User(BaseModel):
    id: int
    name: str
    email: str

class Comment(BaseModel):
    id: int
    text: str
    author: User  # Nested model

class Post(BaseModel):
    id: int
    title: str
    content: str
    author: User  # Nested model
    comments: List[Comment]  # List of nested models

When you use these in FastAPI endpoints:

python
@app.get("/posts/{post_id}", response_model=Post)
def get_post(post_id: int):
    return {
        "id": post_id,
        "title": "My Post",
        "content": "Some content",
        "author": {"id": 1, "name": "Alice", "email": "alice@example.com"},
        "comments": [
            {"id": 1, "text": "Great post!", "author": {"id": 2, "name": "Bob", "email": "bob@example.com"}}
        ]
    }

FastAPI automatically validates the entire nested structure, ensuring all nested objects match their models.

APIs need to return different responses based on success or failure. FastAPI lets you specify multiple response models and set appropriate HTTP status codes.

You control the status code using the status_code parameter:

python
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str

class ErrorResponse(BaseModel):
    error: str
    details: str

@app.post("/items", status_code=201, response_model=Item)
def create_item(item_data: dict):
    return {"id": 1, "name": item_data['name']}

Common HTTP status codes:

• 200: OK (GET success)
• 201: Created (POST/PUT success)
• 400: Bad Request (client error)
• 401: Unauthorized
• 404: Not Found
• 500: Server Error

You can also specify multiple possible responses:

python
@app.get("/items/{item_id}", responses={404: {"description": "Item not found"}})
def get_item(item_id: int):
    if item_id == 999:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"id": item_id}