Waarvoor is response_model?

Question

Accepted Answer

De parameter **`response_model`** declareert de vorm van het antwoord van een endpoint. FastAPI gebruikt het om de geretourneerde gegevens te **valideren, filteren en serialiseren** — en het antwoord in de API-documentatie te documenteren. Zijn belangrijkste taak: ervoor zorgen dat je alleen de beoogde velden blootstelt (bijvoorbeeld nooit een wachtwoord lekken).

## Het probleem: gevoelige velden lekken

```python
class User(BaseModel):
    name: str
    email: str
    password: str        # ⚠️ should NEVER be in the response!

@app.get("/users/{id}")
def get_user(id: int) -> User:
    return db.get_user(id)   # returning the full object would expose the password
```

## De oplossing: een afzonderlijk antwoordmodel

```python
class UserOut(BaseModel):    # the SAFE public shape — no password
    name: str
    email: str

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.get_user(id)   # returns a full user, but FastAPI FILTERS it to UserOut
# response → { "name": "...", "email": "..." }  — password stripped automatically
```

Met `response_model=UserOut` pakt FastAPI wat je ook retourneert en **filtert het** tot alleen de velden die in `UserOut` zijn gedeclareerd — dus het wachtwoord (en andere extra velden) wordt uit het antwoord verwijderd, ook al heb je het volledige object geretourneerd.

## Wat response_model doet

```text
✓ FILTERS the output to only the declared fields (key for hiding sensitive data)
✓ VALIDATES that your response matches the declared schema (catches mistakes)
✓ SERIALIZES the data to JSON correctly
✓ DOCUMENTS the response shape in the OpenAPI/Swagger docs
```

## Moderner alternatief: de annotatie van het retourtype

```python
@app.get("/users/{id}")
def get_user(id: int) -> UserOut:    # the -> return type works like response_model
    return db.get_user(id)
# response_model_exclude_unset=True → omit fields not explicitly set
```

## Waarom het belangrijk is

`response_model` is belangrijk voor zowel **beveiliging** als schoon API-ontwerp.

De kritiekste rol is het voorkomen van onbedoeld gegevenslek — door exact aan te geven welke velden het antwoord moet bevatten, filtert FastAPI alles anders (zoals wachtwoordhashes, interne flags of tokens) eruit, zelfs als je code een volledig databaseobject retourneert, waardoor een veelvoorkomende en ernstige kwetsbaarheid wordt weggewerkt.

Daarbij wordt het antwoord gevalideerd tegen een gedeclareerd schema (het vangen van bugs waar je de verkeerde vorm retourneert), zorgt het voor correcte serialisatie en documenteert het het antwoord in de automatisch gegenereerde API-docs.

Het patroon van het gebruik van afzonderlijke invoer- en uitvoermodellen (waarbij `response_model` controleert wat wordt blootgesteld) is een best practice voor veilige, goed gedefinieerde API's, waardoor dit belangrijke kennis is voor elk endpoint dat gegevens retourneert.