Nested Responses

Learn the fundamentals of nested responses in FastAPI.

🎯 Core Concept

Real-world APIs often return complex, hierarchical data. Nested response models allow you to define and validate arbitrarily deep data structures using Pydantic's composable models.

📖 What You'll Learn

In this section, you'll understand:

• Defining nested Pydantic models

• Response models with multiple levels

• Lists of nested objects

• Complex data hierarchies

• Validation at all levels

💡 Simple Example

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Address(BaseModel):
    street: str
    city: str
    country: str

class User(BaseModel):
    id: int
    name: str
    address: Address

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    return {
        "id": user_id,
        "name": "John Doe",
        "address": {
            "street": "123 Main St",
            "city": "New York",
            "country": "USA"
        }
    }

Lists of Nested Models

class Comment(BaseModel):
    id: int
    text: str
    author: str

class Post(BaseModel):
    id: int
    title: str
    content: str
    comments: List[Comment]

@app.get("/posts/{post_id}", response_model=Post)
async def get_post(post_id: int):
    return {
        "id": post_id,
        "title": "My Post",
        "content": "Content here",
        "comments": [
            {"id": 1, "text": "Great post!", "author": "Jane"},
            {"id": 2, "text": "Thanks for sharing", "author": "Bob"}
        ]
    }

Complex Hierarchies

class Tag(BaseModel):
    name: str

class Author(BaseModel):
    name: str
    email: str

class Article(BaseModel):
    title: str
    author: Author
    tags: List[Tag]
    metadata: dict

@app.get("/articles/{article_id}", response_model=Article)
async def get_article(article_id: int):
    return {...}

🔑 Key Takeaways

• ✅ Understand the purpose of nested 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.