Comment structurer une grande application avec APIRouter ?

Question

Accepted Answer

**`APIRouter`** vous permet de diviser une grande application FastAPI en plusieurs modules — chaque routeur regroupe les endpoints associés (par exemple, toutes les routes `/users`), et l'application principale les inclut. Cela maintient une base de code en croissance organisée et maintenable.

## Définir un routeur dans son propre 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): ...
```

Un `APIRouter` fonctionne comme une mini-application — vous définissez les opérations de chemin sur celui-ci avec les mêmes décorateurs, et un `prefix` s'applique à tous.

## Inclure les routeurs dans l'application 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()` monte les endpoints de chaque routeur dans l'application principale — en assemblant l'API complète à partir de pièces modulaires.

## Une structure de projet typique

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

Chaque fonctionnalité/domaine obtient son propre module routeur — en gardant les routes associées, et la base de code, bien organisées.

## Dépendances et configuration au niveau du routeur

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

Les routeurs peuvent porter des dépendances partagées (par exemple, exiger une authentification admin pour un groupe entier de routes) — appliquées à tous leurs endpoints à la fois.

## Pourquoi c'est important

`APIRouter` est essentiel pour construire n'importe quoi au-delà d'une application FastAPI triviale — sans cela, tous les endpoints vivraient dans un seul fichier, ce qui devient ingérable à mesure que l'API grandit.
\
la comprendre est importante pour **l'organisation du code et la maintenabilité** : diviser les endpoints en modules de routeur basés sur les fonctionnalités (utilisateurs, éléments, authentification) garde le code associé ensemble, rend le projet navigable, et permet aux équipes de travailler indépendamment sur différents domaines.

Le `prefix` et les `tags` gardent les routes et la documentation organisées, et **les dépendances au niveau du routeur** (comme exiger une authentification admin pour un groupe entier) fournissent un comportement propre et à l'échelle du groupe.

Cette structure modulaire est une pratique standard pour les véritables applications FastAPI, rendant `APIRouter` et les modèles d'organisation de projet autour de cela une connaissance importante, pratiquement essentielle pour construire des API évolutives et maintenables.