FastAPI: Splitting Your App with `include_router`

Why it exists

A single Python file for all your API endpoints becomes unmanageable as an application grows. You need a way to split your code into logical modules, like users or items, without rewriting common logic or creating a monolithic, hard-to-read file.

The mental model

app.include_router is like plugging a pre-wired power strip into a wall outlet. The power strip is an APIRouter instance from a separate file, with several API endpoints already defined on it. You use include_router to plug this entire module into your main FastAPI app, making all its endpoints live.

How it works

First, you organize your code into modules, often in a routers directory. In each module file (e.g., routers/users.py), you create an instance of APIRouter and attach path operations (@router.get, @router.post) to it. Then, in your main application file (main.py), you import these router objects and use app.include_router() to mount them, adding all their defined routes to the main app.

When to use it

As soon as your main.py starts to feel crowded. It's standard practice for any production-grade FastAPI project to split logic by domain. For example, you might have separate routers for user management, product inventory, and order processing.

When not to use it

For very small projects or microservices with only a handful of endpoints. In these cases, keeping everything in one file is simpler, and using APIRouter would be unnecessary overhead.

One canonical example

In a file routers/items.py, you define router = APIRouter() and a path @router.get("/{item_id}"). In your main.py, you import it and call app.include_router(items.router, prefix="/items", tags=["items"]). This makes the endpoint available at GET /items/{item_id} and groups it under the "items" tag in the API docs. The prefix argument is crucial for avoiding path conflicts between different routers.