How do you structure a large app with APIRouter?

Question

Accepted Answer

**`APIRouter`** lets you split a large FastAPI app into multiple modules — each router groups related endpoints (e.g. all `/users` routes), and the main app includes them. This keeps a growing codebase organized and maintainable.

## Defining a router in its own module

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # all routes here start with /users
    tags=["users"],           # grouped under "users" in the docs
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

An `APIRouter` works like a mini-app — you define path operations on it with the same decorators, and a `prefix` applies to all of them.

## Including routers in the main app

```python
# main.py
from fastapi import FastAPI
from routers import users, items, auth

app = FastAPI()
app.include_router(users.router)     # mounts /users/* endpoints
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` mounts each router's endpoints into the main app — assembling the full API from modular pieces.

## A typical project structure

```text
app/
  main.py              # creates the app, includes routers
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
    auth.py            # APIRouter for /auth
  models.py            # Pydantic models
  database.py          # DB setup
  dependencies.py      # shared dependencies
```

Each feature/domain gets its own router module — keeping related routes, and the codebase, well-organized.

## Router-level dependencies and config

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # apply a dependency to ALL routes in the router
)
# you can also nest routers via include_router on a router
```

Routers can carry shared dependencies (e.g. require admin auth for an entire group of routes) — applied to all their endpoints at once.

## Why it matters

`APIRouter` is essential for building anything beyond a trivial FastAPI app — without it, all endpoints would live in one file, which becomes unmanageable as the API grows.

Understanding it is important for **code organization and maintainability**: splitting endpoints into feature-based router modules (users, items, auth) keeps related code together, makes the project navigable, and lets teams work on different areas independently.

The `prefix` and `tags` keep routes and documentation organized, and **router-level dependencies** (like requiring admin auth for an entire group) provide clean, group-wide behavior.

This modular structure is standard practice for real FastAPI applications, making `APIRouter` and the project-organization patterns around it important, practically-essential knowledge for building scalable, maintainable APIs.