Come strutturi una grande app con APIRouter?

Question

Accepted Answer

**`APIRouter`** ti permette di dividere una grande app FastAPI in più moduli — ogni router raggruppa endpoint correlati (ad es. tutte le route `/users`), e l'app principale li include. Questo mantiene una codebase in crescita organizzata e manutenibile.

## Definire un router nel suo modulo

```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` funziona come una mini-app — definisci operazioni di path su di esso con gli stessi decoratori, e un `prefix` si applica a tutti loro.

## Includere router nell'app principale

```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 gli endpoint di ogni router nell'app principale — assemblando l'intera API da pezzi modulari.

## Una struttura di progetto tipica

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

Ogni feature/dominio ottiene il suo modulo router — mantenendo le route correlate e la codebase ben organizzate.

## Dipendenze e configurazione a livello di 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
```

I router possono avere dipendenze condivise (ad es. richiedere l'autenticazione admin per un intero gruppo di route) — applicate a tutti i loro endpoint contemporaneamente.

## Perché è importante

`APIRouter` è essenziale per costruire qualsiasi cosa al di là di una semplice app FastAPI — senza di esso, tutti gli endpoint vivrebbero in un file, che diventa ingestibile man mano che l'API cresce.

Comprendere questo è importante per **l'organizzazione del codice e la manutenibilità**: dividere gli endpoint in moduli router basati su feature (utenti, articoli, autenticazione) mantiene il codice correlato insieme, rende il progetto navigabile, e permette ai team di lavorare in aree diverse indipendentemente.

Il `prefix` e `tags` mantengono le route e la documentazione organizzate, e le **dipendenze a livello di router** (come richiedere l'autenticazione admin per un intero gruppo) forniscono un comportamento pulito e a livello di gruppo.

Questa struttura modulare è una pratica standard per le vere applicazioni FastAPI, rendendo `APIRouter` e i pattern di organizzazione del progetto intorno ad esso importanti, conoscenze praticamente essenziali per costruire API scalabili e manutenibili.