Hoe structureer je een grote app met APIRouter?

Question

Accepted Answer

**`APIRouter`** laat je een grote FastAPI app in meerdere modules opsplitsen — elke router groepeert gerelateerde endpoints (bijv. alle `/users` routes), en de hoofdapp voegt ze in. Dit houdt een groeiende codebase georganiseerd en onderhoudbaar.

## Een router in zijn eigen module definiëren

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

Een `APIRouter` werkt als een mini-app — je definieert path operations erop met dezelfde decorators, en een `prefix` is van toepassing op al deze operations.

## Routers in de hoofdapp opnemen

```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()` monteert de endpoints van elke router in de hoofdapp — en assembleert de volledige API uit modulaire onderdelen.

## Een typische projectstructuur

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

Elke feature/domein krijgt zijn eigen router module — wat gerelateerde routes en de codebase goed georganiseerd houdt.

## Router-level dependencies en configuratie

```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 kunnen gedeelde dependencies dragen (bijv. admin-authenticatie vereisen voor een hele groep routes) — toegepast op al hun endpoints tegelijk.

## Waarom het belangrijk is

`APIRouter` is essentieel voor het bouwen van alles voorbij een triviale FastAPI app — zonder het zouden alle endpoints in één bestand leven, wat onbeheersbaar wordt naarmate de API groeit.

Het begrijpen ervan is belangrijk voor **code organisatie en onderhoudsbaarheid**: het opsplitsen van endpoints in feature-gebaseerde router modules (users, items, auth) houdt gerelateerde code bij elkaar, maakt het project navigeerbaar, en laat teams onafhankelijk aan verschillende onderdelen werken.

De `prefix` en `tags` houden routes en documentatie georganiseerd, en **router-level dependencies** (zoals het vereisen van admin-authenticatie voor een hele groep) bieden schoon, groepswijd gedrag.

Deze modulaire structuur is standaardpraktijk voor echte FastAPI-applicaties, wat `APIRouter` en de projectorganisatiepatronen eromheen maakt tot belangrijke, praktisch essentiële kennis voor het bouwen van schaalbare, onderhoudbare API's.