List Responses

Learn the fundamentals of list responses in FastAPI.

🎯 Core Concept

Returning lists of objects is a common API pattern. FastAPI's response models ensure all items in the list match the expected schema, providing type safety and automatic validation.

📖 What You'll Learn

In this section, you'll understand:

• Returning lists of Pydantic models

• Response validation for collections

• Handling empty lists

• Pagination patterns

• Performance considerations for large lists

💡 Simple Example

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()

class Item(BaseModel):
    id: int
    name: str
    price: float

@app.get("/items", response_model=List[Item])
async def list_items():
    return [
        {"id": 1, "name": "Widget", "price": 9.99},
        {"id": 2, "name": "Gadget", "price": 19.99},
    ]

🔍 List Response with Database

@app.get("/users", response_model=List[User])
async def list_users(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    users = db.query(User).offset(skip).limit(limit).all()
    return users

Response Model with Nested Lists

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

class ItemWithCategory(BaseModel):
    id: int
    name: str
    categories: List[Category]

@app.get("/products", response_model=List[ItemWithCategory])
async def list_products():
    return [
        {
            "id": 1,
            "name": "Product A",
            "categories": [
                {"id": 1, "name": "Electronics"},
                {"id": 2, "name": "Gadgets"}
            ]
        }
    ]

🔑 Key Takeaways

• ✅ Understand the purpose of list responses

• ✅ Know when to apply this pattern

• ✅ Recognize its benefits in real-world scenarios

• ✅ Be prepared to use it in your projects

Ready to explore more? Check out the advanced section for production patterns and edge cases.