← Back to DevBytes
Developer Tutorial July 16, 2026 11 min read

Migrating from Legacy Frameworks to FastAPI

Understanding the Migration Landscape

Migrating from a legacy web framework to FastAPI means transitioning your existing Python web application—whether built with Flask, Django REST Framework, Pyramid, or even older WSGI-based frameworks—to FastAPI's modern ASGI-based architecture. This isn't merely a rewrite; it's a strategic evolution that introduces native async support, automatic OpenAPI documentation, and Pydantic-powered validation into your codebase.

Legacy frameworks served us well for years. Flask gave us simplicity. Django gave us batteries-included robustness. But as applications scale and real-time requirements grow, the synchronous, WSGI-bound nature of these frameworks becomes a bottleneck. FastAPI, built on Starlette and Pydantic, offers a path forward that feels familiar to Python developers while unlocking significant performance and developer-experience improvements.

The migration itself can take several forms: a complete rewrite (rarely advisable for large systems), a gradual strangler pattern where FastAPI endpoints replace legacy ones piecemeal, or a hybrid approach where FastAPI sits in front of a legacy backend as a high-performance API gateway. Each approach has its place, and understanding which fits your context is the first critical decision.

Why FastAPI? The Compelling Case for Migration

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

The decision to migrate carries risk. You must justify it with tangible benefits. Here's what FastAPI brings to the table that legacy frameworks struggle to match:

Step-by-Step Migration Guide

The following guide walks you through a practical migration using the strangler pattern—gradually replacing legacy endpoints with FastAPI equivalents while keeping the existing application running. We'll cover Flask and Django REST Framework migrations, as these represent the most common legacy scenarios.

1. Auditing Your Legacy Codebase

Before writing a single line of FastAPI code, catalog every endpoint your legacy application exposes. Group them by dependency complexity: endpoints with few external dependencies (simple CRUD) are low-hanging fruit; those entangled with custom middleware, session management, or complex ORM patterns require more careful planning.

Create a migration spreadsheet or tracker with columns for: endpoint path, HTTP method, dependencies (database tables, external services, middleware), authentication requirements, and priority (low/medium/high). This audit prevents surprises mid-migration.

2. Setting Up FastAPI Alongside Your Legacy App

The strangler pattern works by running FastAPI on a different port (or under a different path prefix) while your legacy app continues to serve traffic. A reverse proxy like Nginx or Traefik routes requests to either backend based on path rules.

First, install FastAPI and an ASGI server in your existing project's virtual environment:

pip install fastapi uvicorn[standard]

Create a minimal FastAPI application file, separate from your legacy entry point:

# fastapi_app/main.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(
    title="Migrated API",
    description="FastAPI gradually replacing legacy endpoints",
    version="0.1.0",
)

# Allow legacy frontend to call both backends during transition
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/v2/health")
async def health_check():
    return {"status": "ok", "framework": "FastAPI"}

# Mount legacy routes here as you migrate them

Run this alongside your legacy app during development:

# Legacy Flask app on port 5000
# FastAPI on port 8000
uvicorn fastapi_app.main:app --host 0.0.0.0 --port 8000 --reload

3. Converting Routes: Flask to FastAPI

Let's walk through converting a typical Flask endpoint to FastAPI. Consider this Flask blueprint that manages a user resource:

# Legacy Flask route (flask_app/routes/users.py)
from flask import Blueprint, request, jsonify, abort
from flask_app.models import User
from flask_app.database import db

users_bp = Blueprint('users', __name__)

@users_bp.route('/users', methods=['GET'])
def list_users():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 20, type=int)
    if per_page > 100:
        abort(400, description="per_page cannot exceed 100")
    users = User.query.paginate(page=page, per_page=per_page)
    return jsonify({
        "users": [u.to_dict() for u in users.items],
        "total": users.total,
        "page": page
    })

@users_bp.route('/users/', methods=['GET'])
def get_user(user_id):
    user = User.query.get(user_id)
    if not user:
        abort(404, description="User not found")
    return jsonify(user.to_dict())

@users_bp.route('/users', methods=['POST'])
def create_user():
    data = request.get_json()
    if not data or 'email' not in data or 'name' not in data:
        abort(400, description="Missing required fields")
    if User.query.filter_by(email=data['email']).first():
        abort(409, description="Email already exists")
    user = User(name=data['name'], email=data['email'])
    db.session.add(user)
    db.session.commit()
    return jsonify(user.to_dict()), 201

Now the FastAPI equivalent. Notice how validation logic moves from imperative checks into declarative Pydantic models, and how the database session becomes a dependency:

# fastapi_app/routers/users.py
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session
from pydantic import BaseModel, EmailStr, Field
from typing import List
from fastapi_app.database import get_db
from fastapi_app.models import User

router = APIRouter(prefix="/users", tags=["Users"])

# --- Pydantic Schemas ---
class UserOut(BaseModel):
    id: int
    name: str
    email: str

    class Config:
        orm_mode = True  # Allows Pydantic to read ORM objects

class UserCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr  # Built-in email validation
    # No manual checks needed—Pydantic validates types and constraints

class PaginatedUsers(BaseModel):
    users: List[UserOut]
    total: int
    page: int
    per_page: int

# --- Endpoints ---
@router.get("/", response_model=PaginatedUsers)
async def list_users(
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100),
    db: Session = Depends(get_db),
):
    # FastAPI validates per_page ≤ 100 automatically via Query(le=100)
    # No manual abort() needed
    offset = (page - 1) * per_page
    users = db.query(User).offset(offset).limit(per_page).all()
    total = db.query(User).count()
    return {
        "users": users,
        "total": total,
        "page": page,
        "per_page": per_page,
    }

@router.get("/{user_id}", response_model=UserOut)
async def get_user(
    user_id: int,  # Path parameter validation is automatic
    db: Session = Depends(get_db),
):
    user = db.query(User).get(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@router.post("/", response_model=UserOut, status_code=201)
async def create_user(
    payload: UserCreate,  # Body is parsed and validated automatically
    db: Session = Depends(get_db),
):
    existing = db.query(User).filter(User.email == payload.email).first()
    if existing:
        raise HTTPException(status_code=409, detail="Email already exists")
    user = User(name=payload.name, email=payload.email)
    db.add(user)
    db.commit()
    db.refresh(user)
    return user

The FastAPI version eliminates roughly half the boilerplate. Validation errors produce structured JSON responses automatically—no more generic abort(400) with hand-written messages. The response_model ensures you never leak sensitive fields (like password hashes) by controlling exactly what gets serialized.

4. Converting Django Views to FastAPI Endpoints

Django REST Framework views involve serializers, viewsets, and a fair amount of magic. Here's a typical DRF viewset:

# Legacy DRF viewset (django_app/api/views.py)
from rest_framework import viewsets, status
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated
from django_app.models import Article
from django_app.serializers import ArticleSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    permission_classes = [IsAuthenticated]

    def get_queryset(self):
        qs = super().get_queryset()
        published = self.request.query_params.get('published', None)
        if published is not None:
            qs = qs.filter(published=published.lower() == 'true')
        return qs

    def perform_create(self, serializer):
        serializer.save(author=self.request.user)

Migrating this to FastAPI gives you explicit control and removes the implicit magic of DRF's perform_create and queryset filtering:

# fastapi_app/routers/articles.py
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session
from pydantic import BaseModel
from typing import List, Optional
from fastapi_app.database import get_db
from fastapi_app.models import Article
from fastapi_app.auth import get_current_user  # Your dependency

router = APIRouter(prefix="/articles", tags=["Articles"])

class ArticleOut(BaseModel):
    id: int
    title: str
    body: str
    author_id: int
    published: bool

    class Config:
        orm_mode = True

class ArticleCreate(BaseModel):
    title: str
    body: str
    published: bool = False

@router.get("/", response_model=List[ArticleOut])
async def list_articles(
    published: Optional[bool] = Query(None),
    db: Session = Depends(get_db),
    current_user = Depends(get_current_user),  # Replaces DRF permission_classes
):
    qs = db.query(Article)
    if published is not None:
        qs = qs.filter(Article.published == published)
    return qs.all()

@router.post("/", response_model=ArticleOut, status_code=201)
async def create_article(
    payload: ArticleCreate,
    db: Session = Depends(get_db),
    current_user = Depends(get_current_user),
):
    article = Article(
        title=payload.title,
        body=payload.body,
        published=payload.published,
        author_id=current_user.id,  # Explicit, not hidden in perform_create
    )
    db.add(article)
    db.commit()
    db.refresh(article)
    return article

@router.get("/{article_id}", response_model=ArticleOut)
async def get_article(
    article_id: int,
    db: Session = Depends(get_db),
    current_user = Depends(get_current_user),
):
    article = db.query(Article).get(article_id)
    if not article:
        raise HTTPException(status_code=404, detail="Article not found")
    return article

The dependency get_current_user replaces DRF's permission classes cleanly. It's a callable that returns the authenticated user or raises an HTTPException—no middleware magic, no method decorators scattered across the codebase.

5. Middleware and Authentication Migration

Legacy frameworks often rely on decorator-based authentication (@login_required in Flask, permission_classes in DRF) or before-request hooks. FastAPI's dependency injection system absorbs most of these patterns elegantly.

Here's a common Flask authentication decorator and its FastAPI counterpart:

# Legacy Flask auth decorator
from functools import wraps
from flask import request, g, abort
import jwt

def require_auth(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('Authorization', '').replace('Bearer ', '')
        if not token:
            abort(401, description="Missing token")
        try:
            payload = jwt.decode(token, 'secret-key', algorithms=['HS256'])
            g.current_user = payload['sub']
        except jwt.InvalidTokenError:
            abort(401, description="Invalid token")
        return f(*args, **kwargs)
    return decorated

# Used like:
@users_bp.route('/me')
@require_auth
def me():
    return jsonify({"user": g.current_user})

In FastAPI, this becomes a dependency—no decorator stacking, no implicit g object:

# FastAPI auth dependency (fastapi_app/auth.py)
from fastapi import Depends, HTTPException, Header
from sqlalchemy.orm import Session
from fastapi_app.database import get_db
from fastapi_app.models import User
import jwt

async def get_current_user(
    authorization: str = Header(None),
    db: Session = Depends(get_db),
) -> User:
    if not authorization:
        raise HTTPException(status_code=401, detail="Missing Authorization header")
    token = authorization.replace("Bearer ", "")
    try:
        payload = jwt.decode(token, "secret-key", algorithms=["HS256"])
        user_id = payload.get("sub")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")
    user = db.query(User).get(int(user_id))
    if not user:
        raise HTTPException(status_code=401, detail="User not found")
    return user  # Injected directly into route parameters

# Used cleanly in routes:
@router.get("/me")
async def get_me(current_user: User = Depends(get_current_user)):
    return {"user": current_user.email}

For middleware that applies globally (CORS, logging, rate limiting), FastAPI uses Starlette's middleware system. Here's a Flask before-request logger converted to FastAPI middleware:

# Legacy Flask before_request hook
@app.before_request
def log_request():
    print(f"Request: {request.method} {request.path}")

# FastAPI equivalent middleware
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import Request
import time

class LoggingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.time()
        print(f"Request: {request.method} {request.url.path}")
        response = await call_next(request)
        duration = time.time() - start
        print(f"Completed in {duration:.3f}s — Status: {response.status_code}")
        return response

app.add_middleware(LoggingMiddleware)

6. Testing Your Migrated Endpoints

FastAPI's TestClient makes testing migrated endpoints straightforward. It works synchronously even with async route handlers, so you can use pytest without any async fixtures:

# tests/test_users.py
from fastapi.testclient import TestClient
from fastapi_app.main import app
from fastapi_app.database import get_db, Base, engine
import pytest

# Override the database dependency for testing
def override_get_db():
    # Use a test database session
    from sqlalchemy.orm import sessionmaker
    TestSession = sessionmaker(bind=engine)
    session = TestSession()
    try:
        yield session
    finally:
        session.close()

app.dependency_overrides[get_db] = override_get_db

client = TestClient(app)

@pytest.fixture(autouse=True)
def clean_db():
    Base.metadata.create_all(bind=engine)
    yield
    Base.metadata.drop_all(bind=engine)

def test_list_users_empty():
    response = client.get("/users/")
    assert response.status_code == 200
    data = response.json()
    assert data["users"] == []
    assert data["total"] == 0

def test_create_and_get_user():
    # Create
    payload = {"name": "Alice", "email": "alice@example.com"}
    response = client.post("/users/", json=payload)
    assert response.status_code == 201
    created = response.json()
    assert created["email"] == "alice@example.com"
    user_id = created["id"]

    # Get by ID
    response = client.get(f"/users/{user_id}")
    assert response.status_code == 200
    assert response.json()["name"] == "Alice"

def test_validation_error():
    # Missing required field 'email'
    response = client.post("/users/", json={"name": "Bob"})
    assert response.status_code == 422
    detail = response.json()["detail"]
    assert any("email" in str(e) for e in detail)

The dependency_overrides dictionary lets you swap production dependencies for test doubles without changing route signatures. This is cleaner than monkey-patching or maintaining separate test application factories.

Best Practices for a Smooth Migration

Conclusion

Migrating from Flask, Django REST Framework, or any legacy WSGI framework to FastAPI is not a cosmetic upgrade—it fundamentally improves performance, developer ergonomics, and API documentation quality. The strangler pattern lets you execute this migration incrementally, reducing risk while delivering value with each migrated endpoint group. By moving validation into Pydantic models, authentication into dependency callables, and serialization into response_model declarations, you eliminate entire categories of boilerplate and runtime errors. The result is a codebase that's leaner, faster, self-documenting, and ready for the async-first future of Python web development. Start with your simplest CRUD endpoints, build momentum, and let FastAPI's automatic documentation tell the story of your progress to the entire team.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles