FastAPI Complete Guide: Building Production APIs

Introduction to FastAPI

FastAPI is a modern, high-performance Python web framework for building APIs with Python 3.6+ using type hints. It’s built on top of ASGI (Asynchronous Server Gateway Interface) and combines the best aspects of modern Python development: automatic documentation, input validation, async support, and exceptional performance.

Unlike traditional frameworks like Django and Flask that use WSGI (synchronous), FastAPI leverages ASGI for true asynchronous request handling, enabling dramatic performance improvements for I/O-bound operations. FastAPI automatically generates interactive API documentation (Swagger UI and ReDoc), validates request data, and provides intuitive dependency injection.

According to independent benchmarks, FastAPI handles 15,000-20,000 requests per second compared to Flask’s 2,000-3,000 and Django’s similar range. This makes FastAPI the ideal choice for building high-performance microservices, real-time applications, and APIs serving thousands of concurrent requests.

Why Choose FastAPI?

Performance Comparison

Automatic Documentation

FastAPI automatically generates interactive API documentation without any extra code. Simply use type hints in your code, and FastAPI creates Swagger UI and ReDoc documentation automatically.

Built-in Data Validation

Using Pydantic models, FastAPI validates incoming request data automatically. If data doesn’t match the defined schema, FastAPI returns detailed validation errors without you writing validation code.

Native Async/Await Support

Write concurrent code using Python’s modern async/await syntax. FastAPI handles the complexity of managing concurrent requests while you focus on business logic.

Getting Started with FastAPI

Installation

pip install fastapi uvicorn[standard]

FastAPI is the framework, while Uvicorn is the ASGI server that runs your application. The [standard] extras include uvloop for better performance.

Your First FastAPI Application

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

# Run with: uvicorn main:app --reload

Running the Application

uvicorn main:app --reload

The --reload flag enables auto-reload during development. Visit http://localhost:8000/docs to see the interactive Swagger UI documentation.

API Basics: Request and Response Handling

HTTP Methods and Route Parameters

from fastapi import FastAPI

app = FastAPI()

# GET request
@app.get("/items/{item_id}")
async def get_item(item_id: int):
    return {"item_id": item_id}

# POST request
@app.post("/items/")
async def create_item(name: str, price: float):
    return {"name": name, "price": price}

# PUT request
@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    return {"item_id": item_id, "name": name}

# DELETE request
@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"deleted": item_id}

Request Body with Pydantic Models

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

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

@app.post("/items/")
async def create_item(item: Item):
    return item

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

Query Parameters and Path Parameters

from fastapi import FastAPI

app = FastAPI()

# Path parameter (required)
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

# Query parameter (optional)
@app.get("/items/")
async def list_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

# Mixed parameters
@app.get("/users/{user_id}/items/{item_id}")
async def get_user_item(user_id: int, item_id: int, q: str = None):
    return {"user_id": user_id, "item_id": item_id, "q": q}

Data Validation with Pydantic

Comprehensive Validation Example

from fastapi import FastAPI
from pydantic import BaseModel, Field, validator
from typing import Optional, List
from datetime import datetime

app = FastAPI()

class Item(BaseModel):
    name: str = Field(..., min_length=1, max_length=50)
    description: Optional[str] = Field(None, max_length=200)
    price: float = Field(..., gt=0)  # Greater than 0
    quantity: int = Field(default=1, ge=0)  # Greater than or equal to 0
    tags: List[str] = []
    created_at: datetime = datetime.now()
    
    @validator('name')
    def name_must_be_alphanumeric(cls, v):
        if not v.replace(" ", "").isalnum():
            raise ValueError('Name must be alphanumeric')
        return v

@app.post("/items/")
async def create_item(item: Item):
    return item

# FastAPI automatically validates and returns errors like:
# {
#   "detail": [
#     {
#       "loc": ["body", "price"],
#       "msg": "ensure this value is greater than 0",
#       "type": "value_error.number.not_gt"
#     }
#   ]
# }

Dependency Injection System

Basic Dependencies

from fastapi import FastAPI, Depends

app = FastAPI()

# Simple dependency
def get_query(q: str = None, skip: int = 0):
    return {"q": q, "skip": skip}

@app.get("/items/")
async def read_items(common: dict = Depends(get_query)):
    return {"query": common}

# Class-based dependency
class CommonQueryParams:
    def __init__(self, skip: int = 0, limit: int = 10):
        self.skip = skip
        self.limit = limit

@app.get("/users/")
async def list_users(commons: CommonQueryParams = Depends()):
    return {"skip": commons.skip, "limit": commons.limit}

Nested Dependencies

from fastapi import FastAPI, Depends, HTTPException

app = FastAPI()

# Level 1 dependency
def get_user_id(token: str = None) -> int:
    if not token:
        raise HTTPException(status_code=401, detail="Missing token")
    return int(token)  # Simplified for example

# Level 2 dependency depends on Level 1
def get_user(user_id: int = Depends(get_user_id)):
    return {"id": user_id, "name": "John Doe"}

# Endpoint uses Level 2 dependency
@app.get("/me/")
async def read_current_user(user: dict = Depends(get_user)):
    return user

Security and Authentication

JWT Authentication

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthCredentials
import jwt
from datetime import datetime, timedelta

app = FastAPI()
security = HTTPBearer()
SECRET_KEY = "your-secret-key-change-in-production"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_delta: timedelta = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(hours=24)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

async def verify_token(credentials: HTTPAuthCredentials = Depends(security)):
    try:
        payload = jwt.decode(credentials.credentials, SECRET_KEY, algorithms=[ALGORITHM])
        user_id: int = payload.get("sub")
        if user_id is None:
            raise HTTPException(status_code=401, detail="Invalid token")
        return user_id
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")

@app.post("/login/")
async def login(username: str, password: str):
    # Verify credentials (simplified)
    token = create_access_token({"sub": 1})
    return {"access_token": token, "token_type": "bearer"}

@app.get("/protected/")
async def protected_route(user_id: int = Depends(verify_token)):
    return {"user_id": user_id, "message": "You are authenticated"}

API Key Authentication

from fastapi import FastAPI, Depends, HTTPException, Header

app = FastAPI()

async def verify_api_key(x_token: str = Header(...)):
    if x_token != "your-secret-api-key":
        raise HTTPException(status_code=400, detail="Invalid API Key")
    return x_token

@app.get("/api/data/")
async def get_data(api_key: str = Depends(verify_api_key)):
    return {"data": "sensitive information"}

Database Integration

SQLAlchemy with FastAPI

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session
from fastapi import FastAPI, Depends
from pydantic import BaseModel

# Database setup
DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

# SQLAlchemy model
class UserDB(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)

# Pydantic model
class User(BaseModel):
    id: int
    name: str
    email: str
    
    class Config:
        from_attributes = True

# Dependency to get database session
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# Create tables
Base.metadata.create_all(bind=engine)

app = FastAPI()

@app.post("/users/", response_model=User)
async def create_user(user: User, db: Session = Depends(get_db)):
    db_user = UserDB(**user.dict())
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

@app.get("/users/{user_id}", response_model=User)
async def read_user(user_id: int, db: Session = Depends(get_db)):
    return db.query(UserDB).filter(UserDB.id == user_id).first()

Performance Optimization

Async vs Sync Endpoints

Use async def for I/O-bound operations (database queries, API calls) and def for CPU-bound operations that need to run in a thread pool.

from fastapi import FastAPI
import asyncio
import time

app = FastAPI()

# ✓ Good: Async for I/O operations
@app.get("/fast-io/")
async def io_operation():
    await asyncio.sleep(1)  # Simulates I/O
    return {"status": "done"}

# ✓ Good: Sync for CPU operations
@app.get("/cpu-task/")
def cpu_operation():
    time.sleep(1)  # FastAPI runs this in thread pool
    return {"status": "computed"}

# ✗ Bad: Sync code in async context
@app.get("/slow-endpoint/")
async def slow_endpoint():
    time.sleep(5)  # Blocks entire event loop!
    return {"status": "bad"}

Background Tasks

from fastapi import FastAPI, BackgroundTasks
import time

app = FastAPI()

def write_log(message: str):
    with open("log.txt", mode="a") as log:
        log.write(message + "\n")

@app.post("/send-notification/")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Notification sent to {email}")
    return {"message": "Notification sent in the background"}

Production Server Configuration

# Run FastAPI with Gunicorn + Uvicorn workers for production
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

# Or use uvloop for even better performance
pip install uvloop

# Then run with uvloop enabled
uvicorn main:app --loop uvloop --workers 4

Production Deployment

Docker Deployment

FROM python:3.11

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

# requirements.txt
fastapi==0.104.1
uvicorn[standard]==0.24.0
sqlalchemy==2.0.23
pydantic==2.5.0
python-jose[cryptography]==3.3.0
python-multipart==0.0.6

Production Architecture

# Docker Compose for production setup
version: '3.8'

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/fastapi
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=fastapi
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - api
    restart: unless-stopped

volumes:
  postgres_data:

Nginx Configuration

upstream fastapi {
    server api:8000;
}

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://fastapi;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Health Check Endpoint

from fastapi import FastAPI
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/health/")
async def health_check():
    """Liveness check - is the service running?"""
    return {"status": "alive"}

@app.get("/ready/")
async def readiness_check(db: Session = Depends(get_db)):
    """Readiness check - can the service handle requests?"""
    try:
        # Test database connectivity
        db.execute("SELECT 1")
        return {"status": "ready"}
    except Exception as e:
        raise HTTPException(status_code=503, detail="Service unavailable")

The Bottom Line

FastAPI represents the modern approach to building Python APIs. Its combination of automatic documentation, built-in validation, native async support, and exceptional performance makes it the ideal choice for building production APIs that need to handle thousands of concurrent requests.

Key takeaways for building production FastAPI applications:

• Use type hints and Pydantic models for automatic validation
• Leverage async/await for I/O-bound operations
• Implement proper authentication and authorization
• Use dependency injection for clean, testable code
• Configure multiple workers for production deployments
• Implement comprehensive logging and monitoring
• Use containerization and CI/CD for reliable deployments
• Always validate inputs and handle errors gracefully