Skip to main content

Response Models

Learn how to define, validate, and document API responses using Pydantic models, ensuring type safety and consistent data structures.

Basic Response Models​

Defining Response Models​

Use response_model to specify the structure of your response:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/", response_model=Item)
def create_item(item: Item):
    return item

Response Model Benefits​

  1. Data Filtering: Only return fields defined in the response model
  2. Validation: Ensure response data matches the expected structure
  3. Documentation: Automatic schema generation for API docs
  4. Type Safety: Type checking and editor autocomplete

Response Model Features​

Excluding Fields​

Filter out sensitive or unnecessary data:

class UserIn(BaseModel):
    username: str
    password: str
    email: str
    full_name: str | None = None

class UserOut(BaseModel):
    username: str
    email: str
    full_name: str | None = None

@app.post("/users/", response_model=UserOut)
def create_user(user: UserIn):
    # Password is not included in response
    return user

Response Model Exclude​

Exclude specific fields dynamically:

@app.get(
    "/items/{item_id}",
    response_model=Item,
    response_model_exclude={"tax"}
)
def read_item(item_id: int):
    return items_db[item_id]

Response Model Include​

Include only specific fields:

@app.get(
    "/items/{item_id}",
    response_model=Item,
    response_model_include={"name", "price"}
)
def read_item(item_id: int):
    return items_db[item_id]

Exclude Unset Values​

Only return fields that were explicitly set:

@app.get(
    "/items/{item_id}",
    response_model=Item,
    response_model_exclude_unset=True
)
def read_item(item_id: int):
    # If tax was not set, it won't appear in response
    return Item(name="Item", price=10.0)

Exclude Defaults​

Exclude fields that have default values:

@app.get(
    "/items/{item_id}",
    response_model=Item,
    response_model_exclude_defaults=True
)
def read_item(item_id: int):
    return items_db[item_id]

Exclude None Values​

Remove fields with None values:

@app.get(
    "/items/{item_id}",
    response_model=Item,
    response_model_exclude_none=True
)
def read_item(item_id: int):
    return items_db[item_id]

Multiple Response Models​

Different Responses for Different Status Codes​

from typing import Union

class ItemBase(BaseModel):
    name: str
    price: float

class ItemCreate(ItemBase):
    pass

class ItemResponse(ItemBase):
    id: int
    created_at: str

class ErrorResponse(BaseModel):
    error: str
    detail: str

@app.post(
    "/items/",
    response_model=ItemResponse,
    responses={
        201: {"model": ItemResponse},
        400: {"model": ErrorResponse}
    }
)
def create_item(item: ItemCreate):
    if item.price < 0:
        raise HTTPException(
            status_code=400,
            detail="Price must be positive"
        )

    new_item = ItemResponse(
        id=1,
        name=item.name,
        price=item.price,
        created_at="2024-01-01"
    )
    return new_item

Union Response Types​

from typing import Union

class SuccessResponse(BaseModel):
    message: str
    data: dict

class ErrorResponse(BaseModel):
    error: str

@app.get("/items/{item_id}")
def read_item(item_id: int) -> Union[SuccessResponse, ErrorResponse]:
    if item_id not in items_db:
        return ErrorResponse(error="Item not found")
    return SuccessResponse(message="Success", data=items_db[item_id])

List Responses​

Returning Lists​

from typing import List

@app.get("/items/", response_model=List[Item])
def read_items():
    return items_db.values()

Paginated Lists​

from typing import List

class PaginatedResponse(BaseModel):
    items: List[Item]
    total: int
    page: int
    page_size: int

@app.get("/items/", response_model=PaginatedResponse)
def read_items(page: int = 1, page_size: int = 10):
    start = (page - 1) * page_size
    end = start + page_size

    items = list(items_db.values())[start:end]

    return PaginatedResponse(
        items=items,
        total=len(items_db),
        page=page,
        page_size=page_size
    )

Nested Response Models​

Complex Nested Structures​

from typing import List

class Tag(BaseModel):
    name: str

class Image(BaseModel):
    url: str
    alt_text: str

class ItemDetail(BaseModel):
    id: int
    name: str
    description: str
    price: float
    tags: List[Tag]
    images: List[Image]

@app.get("/items/{item_id}", response_model=ItemDetail)
def read_item(item_id: int):
    return ItemDetail(
        id=item_id,
        name="Laptop",
        description="High-performance laptop",
        price=1299.99,
        tags=[Tag(name="electronics"), Tag(name="computers")],
        images=[
            Image(url="http://example.com/img1.jpg", alt_text="Front view"),
            Image(url="http://example.com/img2.jpg", alt_text="Side view")
        ]
    )

Recursive Models​

class Category(BaseModel):
    name: str
    subcategories: List['Category'] = []

Category.model_rebuild()  # Required for recursive models

@app.get("/categories/", response_model=List[Category])
def read_categories():
    return [
        Category(
            name="Electronics",
            subcategories=[
                Category(name="Computers"),
                Category(name="Phones")
            ]
        ),
        Category(name="Clothing")
    ]

Response Customization​

Custom JSON Encoder​

from datetime import datetime
from fastapi.encoders import jsonable_encoder

class CustomItem(BaseModel):
    name: str
    created_at: datetime

    class Config:
        json_encoders = {
            datetime: lambda v: v.strftime("%Y-%m-%d %H:%M:%S")
        }

@app.get("/items/{item_id}", response_model=CustomItem)
def read_item(item_id: int):
    return CustomItem(name="Item", created_at=datetime.now())

Field Aliases​

from pydantic import Field

class Item(BaseModel):
    name: str
    item_price: float = Field(..., alias="price")
    tax_amount: float | None = Field(None, alias="tax")

    class Config:
        populate_by_name = True

@app.get("/items/{item_id}", response_model=Item)
def read_item(item_id: int):
    # Response will use aliases: "price" and "tax"
    return Item(name="Item", price=10.0, tax=1.5)

Response Status Codes​

Setting Status Codes​

from fastapi import status

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    return item

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(item_id: int):
    return None

Dynamic Status Codes​

from fastapi import Response

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item, response: Response):
    if item_id in items_db:
        response.status_code = status.HTTP_200_OK
        items_db[item_id] = item
    else:
        response.status_code = status.HTTP_201_CREATED
        items_db[item_id] = item

    return item

Response Headers​

Setting Response Headers​

from fastapi import Response

@app.get("/items/{item_id}")
def read_item(item_id: int, response: Response):
    response.headers["X-Custom-Header"] = "custom-value"
    response.headers["X-Item-ID"] = str(item_id)
    return {"item_id": item_id}

Custom Response Class​

from fastapi.responses import JSONResponse

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return JSONResponse(
        content={"item_id": item_id},
        headers={"X-Custom-Header": "value"},
        status_code=200
    )

Different Response Types​

JSON Response (Default)​

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}  # Automatically JSONResponse

Plain Text Response​

from fastapi.responses import PlainTextResponse

@app.get("/text/", response_class=PlainTextResponse)
def read_text():
    return "Hello, World!"

HTML Response​

from fastapi.responses import HTMLResponse

@app.get("/html/", response_class=HTMLResponse)
def read_html():
    return """
    <html>
        <head><title>FastAPI</title></head>
        <body><h1>Hello, World!</h1></body>
    </html>
    """

File Response​

from fastapi.responses import FileResponse

@app.get("/download/{filename}")
def download_file(filename: str):
    return FileResponse(
        path=f"files/{filename}",
        filename=filename,
        media_type="application/octet-stream"
    )

Streaming Response​

from fastapi.responses import StreamingResponse
import io

@app.get("/stream/")
def stream_data():
    def generate():
        for i in range(100):
            yield f"Line {i}\n"

    return StreamingResponse(
        generate(),
        media_type="text/plain"
    )

Redirect Response​

from fastapi.responses import RedirectResponse

@app.get("/old-url")
def old_url():
    return RedirectResponse(url="/new-url")

@app.get("/redirect/{item_id}")
def redirect_item(item_id: int):
    return RedirectResponse(
        url=f"/items/{item_id}",
        status_code=status.HTTP_303_SEE_OTHER
    )

Response Validation​

Output Validation​

from pydantic import BaseModel, validator

class ItemResponse(BaseModel):
    name: str
    price: float
    final_price: float

    @validator('final_price')
    def validate_final_price(cls, v, values):
        if v < 0:
            raise ValueError('Final price cannot be negative')
        if 'price' in values and v > values['price'] * 2:
            raise ValueError('Final price too high')
        return v

@app.get("/items/{item_id}", response_model=ItemResponse)
def read_item(item_id: int):
    return ItemResponse(
        name="Item",
        price=100.0,
        final_price=150.0
    )

Generic Response Wrappers​

Success/Error Wrapper​

from typing import Generic, TypeVar, Optional

T = TypeVar('T')

class ResponseWrapper(BaseModel, Generic[T]):
    success: bool
    data: Optional[T] = None
    error: Optional[str] = None
    message: str = ""

@app.get("/items/{item_id}", response_model=ResponseWrapper[Item])
def read_item(item_id: int):
    if item_id not in items_db:
        return ResponseWrapper(
            success=False,
            error="Item not found",
            message="The requested item does not exist"
        )

    return ResponseWrapper(
        success=True,
        data=items_db[item_id],
        message="Item retrieved successfully"
    )

API Response Standard​

from datetime import datetime

class ApiResponse(BaseModel, Generic[T]):
    timestamp: datetime
    status: str
    data: T
    metadata: dict = {}

@app.get("/items/{item_id}", response_model=ApiResponse[Item])
def read_item(item_id: int):
    return ApiResponse(
        timestamp=datetime.now(),
        status="success",
        data=items_db[item_id],
        metadata={"version": "1.0"}
    )

Response Compression​

Enable Gzip Compression​

from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(GZipMiddleware, minimum_size=1000)

@app.get("/large-response/")
def large_response():
    # Response will be compressed if > 1000 bytes
    return {"data": "x" * 10000}

Best Practices​

  1. Use Response Models: Always define response models for type safety and documentation
  2. Consistent Structure: Use consistent response structures across your API
  3. Proper Status Codes: Use appropriate HTTP status codes (200, 201, 204, etc.)
  4. Error Responses: Define clear error response models
  5. Pagination: Implement pagination for list endpoints
  6. Field Filtering: Allow clients to specify which fields they need
  7. Versioning: Include API version in responses when needed
  8. Compression: Enable compression for large responses
  9. Caching Headers: Set appropriate cache headers
  10. Response Time: Monitor and optimize response times

Response models are a powerful feature in FastAPI that ensure your API returns consistent, well-documented, and validated data structures. Master these patterns to build reliable APIs.