Response Model — Return Type

Basic Response Model

Declare the response type with response_model:

from pydantic import BaseModel
from justapi import JustAPIApp

class User(BaseModel):
    id: int
    name: str
    email: str
    password: str

app = JustAPIApp()

@app.get("/users/{user_id}", response_model=User)
def get_user(user_id: int):
    return {"id": user_id, "name": "Alice", "email": "alice@example.com", "password": "secret"}

The password field is automatically excluded from the response because it's not in the response model. This is a security feature — you don't accidentally leak sensitive data.

Filtering Response Fields

Use a separate model for output:

class UserOut(BaseModel):
    id: int
    name: str

@app.get("/users/{user_id}", response_model=UserOut)
def get_user(user_id: int):
    return {"id": user_id, "name": "Alice", "email": "alice@example.com"}

Only id and name appear in the response.

Exclude Fields

@app.get(
    "/users/{user_id}",
    response_model=User,
    response_model_exclude={"password"},
)
def get_user(user_id: int):
    return {"id": user_id, "name": "Alice", "email": "alice@example.com", "password": "secret"}

Include Fields

@app.get(
    "/users/{user_id}",
    response_model=UserOut,
    response_model_include={"id", "name"},
)
def get_user(user_id: int):
    return {"id": user_id, "name": "Alice"}

response_model_exclude_unset

This is useful when working with databases that return optional fields. It excludes fields that were not explicitly set:

from pydantic import BaseModel
from typing import Optional

class User(BaseModel):
    id: int
    name: str
    email: Optional[str] = None
    bio: Optional[str] = None

app = JustAPIApp()

@app.get("/users/{user_id}", response_model=User, response_model_exclude_unset=True)
def get_user(user_id: int):
    # Database returns only set fields
    return {"id": 1, "name": "Alice"}
    # email and bio are excluded because they weren't set

Without exclude_unset, the response would include "email": null, "bio": null. With it, only id and name appear.

response_model_exclude_defaults

Excludes fields that have their default value:

@app.get("/users/{user_id}", response_model=User, response_model_exclude_defaults=True)
def get_user(user_id: int):
    return {"id": 1, "name": "Alice", "email": None, "bio": None}
    # email and bio are excluded because None is the default

response_model_exclude_none

Excludes fields that are None:

@app.get("/users/{user_id}", response_model=User, response_model_exclude_none=True)
def get_user(user_id: int):
    return {"id": 1, "name": "Alice", "email": None, "bio": None}
    # email and bio are excluded because they're None

Disable Response Model

@app.get("/raw", response_model=None)
def raw():
    return {"anything": "goes"}

With response_model=None, no response filtering is applied.

Multiple Response Models

from typing import Union

@app.get(
    "/users/{user_id}",
    response_model=Union[UserOut, dict],
    responses={404: {"model": dict}},
)
def get_user(user_id: int):
    if user_id == 0:
        return {"error": "not found"}
    return {"id": user_id, "name": "Alice"}

Return Type Annotation

You can also use the Python return type annotation:

@app.get("/users/{user_id}")
def get_user(user_id: int) -> UserOut:
    return {"id": user_id, "name": "Alice"}

JustAPI uses the return type as the response model automatically.