A cosa serve response_model?

Question

Accepted Answer

Il parametro **`response_model`** dichiara la forma della risposta di un endpoint. FastAPI lo utilizza per **convalidare, filtrare e serializzare** i dati restituiti — e per documentare la risposta nella documentazione dell'API. Il suo compito più importante: assicurarsi di esporre solo i campi previsti (ad esempio, non perdere mai una password).

## Il problema: perdita di campi sensibili

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

## La soluzione: un modello di risposta separato

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

Con `response_model=UserOut`, FastAPI prende tutto ciò che restituisci e **lo filtra** mantenendo solo i campi dichiarati in `UserOut` — quindi la password (e qualsiasi altro campo aggiuntivo) viene rimosso dalla risposta, anche se hai restituito l'oggetto completo.

## Cosa fa response_model

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

## Alternativa moderna: l'annotazione del tipo di ritorno

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

## Perché è importante

`response_model` è importante sia per la **sicurezza** che per un design pulito dell'API.

Il suo ruolo più critico è prevenire perdite accidentali di dati — dichiarando esattamente quali campi dovrebbe contenere la risposta, FastAPI filtra tutto il resto (come password hash, flag interni o token) anche se il tuo codice restituisce un oggetto database completo, eliminando una vulnerabilità comune e seria.

Oltre a ciò, convalida le tue risposte rispetto a uno schema dichiarato (individuando bug dove restituisci una forma sbagliata), assicura la corretta serializzazione e documenta la risposta nella documentazione API generata automaticamente.

Il modello di utilizzo di modelli di input e output separati (con `response_model` che controlla cosa viene esposto) è una best practice per API sicure e ben definite, rendendo questa conoscenza importante per qualsiasi endpoint che restituisce dati.