¿Para qué sirve response_model?

Question

Accepted Answer

El parámetro **`response_model`** declara la forma de la respuesta de un endpoint. FastAPI lo utiliza para **validar, filtrar y serializar** los datos devueltos — y para documentar la respuesta en los documentos de la API. Su trabajo más importante: asegurar que solo expongas los campos previstos (por ejemplo, nunca filtrar una contraseña).

## El problema: filtrar campos sensibles

```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 solución: un modelo de respuesta separado

```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 toma lo que devuelves y **lo filtra** para incluir solo los campos declarados en `UserOut` — así la contraseña (y cualquier otro campo adicional) se elimina de la respuesta, aunque hayas devuelto el objeto completo.

## Qué hace 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: la anotación de tipo de retorno

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

## Por qué es importante

`response_model` es importante tanto para la **seguridad** como para un diseño limpio de la API.

Su rol más crítico es prevenir filtraciones accidentales de datos — al declarar exactamente qué campos debe contener la respuesta, FastAPI filtra todo lo demás (como hashes de contraseñas, banderas internas o tokens) incluso si tu código devuelve un objeto de base de datos completo, eliminando una vulnerabilidad común y grave.

Más allá de eso, valida tus respuestas contra un esquema declarado (detectando errores donde devuelves la forma incorrecta), asegura la serialización correcta y documenta la respuesta en los documentos de la API generados automáticamente.

El patrón de usar modelos de entrada y salida separados (con `response_model` controlando lo que se expone) es una mejor práctica para APIs seguras y bien definidas, haciendo que este sea un conocimiento importante para cualquier endpoint que devuelva datos.