¿Cómo estructuras una aplicación grande con APIRouter?

Question

Accepted Answer

**`APIRouter`** te permite dividir una aplicación FastAPI grande en múltiples módulos — cada router agrupa endpoints relacionados (p. ej. todas las rutas `/users`), y la aplicación principal los incluye. Esto mantiene una base de código en crecimiento organizada y mantenible.

## Definiendo un router en su propio módulo

```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): ...
```

Un `APIRouter` funciona como una mini-aplicación — defines path operations en él con los mismos decoradores, y un `prefix` se aplica a todos ellos.

## Incluyendo routers en la aplicación principal

```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()` monta los endpoints de cada router en la aplicación principal — ensambla la API completa a partir de piezas modulares.

## Una estructura de proyecto típica

```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
```

Cada característica/dominio obtiene su propio módulo router — manteniendo rutas relacionadas, y la base de código bien organizada.

## Dependencias y configuración a nivel de router

```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
```

Los routers pueden llevar dependencias compartidas (p. ej. requerir autenticación de admin para un grupo completo de rutas) — aplicadas a todos sus endpoints a la vez.

## Por qué es importante

`APIRouter` es esencial para construir cualquier cosa más allá de una aplicación FastAPI trivial — sin él, todos los endpoints vivirían en un archivo, lo que se vuelve inmanejable a medida que la API crece.

Entender esto es importante para **organización de código y mantenibilidad**: dividir endpoints en módulos router basados en características (usuarios, artículos, autenticación) mantiene el código relacionado junto, hace el proyecto navegable, y permite que los equipos trabajen en áreas diferentes de forma independiente.

El `prefix` y `tags` mantienen las rutas y la documentación organizadas, y las **dependencias a nivel de router** (como requerir autenticación de admin para un grupo completo) proporcionan comportamiento limpio a nivel de grupo.

Esta estructura modular es práctica estándar para aplicaciones FastAPI reales, haciendo que `APIRouter` y los patrones de organización de proyecto alrededor de él sean conocimiento importante, prácticamente esencial para construir APIs escalables y mantenibles.