What is response_model for?

Question

Accepted Answer

The **`response_model`** parameter declares the shape of an endpoint's response. FastAPI uses it to **validate, filter, and serialize** the returned data — and to document the response in the API docs. Its most important job: ensuring you only expose the intended fields (e.g. never leaking a password).

## The problem: leaking sensitive fields

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

## The solution: a separate response model

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

With `response_model=UserOut`, FastAPI takes whatever you return and **filters it down** to only the fields declared in `UserOut` — so the password (and any other extra fields) is stripped from the response, even though you returned the full object.

## What response_model does

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

## Modern alternative: the return type annotation

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

## Why it matters

`response_model` is important for both **security** and clean API design.

Its most critical role is preventing accidental data leaks — by declaring exactly which fields the response should contain, FastAPI filters out everything else (like password hashes, internal flags, or tokens) even if your code returns a full database object, eliminating a common and serious vulnerability.

Beyond that, it validates your responses against a declared schema (catching bugs where you return the wrong shape), ensures correct serialization, and documents the response in the auto-generated API docs.

The pattern of using separate input and output models (with `response_model` controlling what's exposed) is a best practice for safe, well-defined APIs, making this important knowledge for any endpoint that returns data.