Recap — Separation of Concerns and Response Shaping

# Separation of Concerns and Response Shaping A common temptation: use one model class for both DB rows and API responses. Resist it. Separation of these layers is one of the biggest quality wins in API design. ## Why separate ### SQLAlchemy models = DB rows ```python class User(Base): id: Mapped[int] = mapped_column(primary_key=True) email: Mapped[str] password_hash: Mapped[str] # SECURITY: never expose is_admin: Mapped[bool] # SECURITY: never expose internal_notes: Mapped[str | None] # admin-only field created_at: Mapped[datetime] deleted_at: Mapped[datetime | None] # soft-delete flag ``` These represent every column. Some are sensitive; some are internal-only. ### Pydantic response = what client sees ```python class UserResponse(BaseModel): id: int email: str created_at: datetime # No password_hash, no is_admin, no internal_notes, no deleted_at model_config = ConfigDict(from_attributes=True) ``` Only fields safe and meaningful for the client. ### Pydantic request = what client sends ```python class UserCreate(BaseModel): email: EmailStr password: str # plaintext from client; hashed before storing name: str ``` Yet another shape. Includes password but not id (server generates). ## The conversion pattern ```python @app.post("/users", response_model=UserResponse) def create_user(payload: UserCreate, db: Session = Depends(get_db)): # 1. Pydantic input model already validated # 2. Process for storage user = User( email=payload.email, name=payload.name, password_hash=hash_password(payload.password), ) db.add(user) db.commit() db.refresh(user) # 3. Return ORM object; FastAPI converts via response_model + from_attributes return user ``` `from_attributes=True` on UserResponse lets Pydantic introspect the ORM object's attributes. The response_model strips fields not in UserResponse. Alternative explicit conversion: ```python return UserResponse.model_validate(user) ``` Both work; FastAPI does it automatically when response_model is set. ## Multiple response shapes per resource For different contexts: ```python class UserPublic(BaseModel): id: int name: str # Public info only class UserPrivate(BaseModel): id: int email: str name: str created_at: datetime # For the user themselves class UserAdmin(BaseModel): id: int email: str name: str is_admin: bool internal_notes: str | None # For admins @app.get("/users/{user_id}/public", response_model=UserPublic) def get_public_user(user_id: int): ... @app.get("/users/me", response_model=UserPrivate) def get_me(current_user: User = Depends(get_current_user)): return current_user @app.get("/admin/users/{user_id}", response_model=UserAdmin) def get_user_admin(user_id: int, admin: User = Depends(require_admin)): ... ``` Same DB model; different response models per use case. Clean. ## Nested relationships When you want related data in the response: ```python class PostResponse(BaseModel): id: int title: str content: str model_config = ConfigDict(from_attributes=True) class UserWithPostsResponse(BaseModel): id: int name: str posts: list[PostResponse] model_config = ConfigDict(from_attributes=True) @app.get("/users/{user_id}", response_model=UserWithPostsResponse) def get_user_with_posts(user_id: int, db: Session = Depends(get_db)): user = db.execute( select(User).where(User.id == user_id).options(selectinload(User.posts)) ).scalar_one() return user ``` The relationship `user.posts` becomes `posts: list[PostResponse]` in the response. Eager-load to avoid N+1. ## Avoiding the leak Common mistake: ```python @app.get("/users/{user_id}") # NO response_model def get_user(user_id: int, db: Session = Depends(get_db)): return db.get(User, user_id) ``` Returns: `{"id": 1, "email": "...", "password_hash": "$2b$12$...", "is_admin": true, ...}`. PASSWORD HASH IN THE RESPONSE. Even though it's "hashed", you've leaked it. Plus revealed admin status. This is a real security issue. Fix: ```python @app.get("/users/{user_id}", response_model=UserResponse) def get_user(user_id: int, db: Session = Depends(get_db)): return db.get(User, user_id) ``` Now only fields in UserResponse are returned. ## When response_model isn't enough For computed fields or transformations: ```python class UserResponse(BaseModel): id: int email: str display_name: str # not directly on User model avatar_url: str @app.get("/users/{user_id}", response_model=UserResponse) def get_user(user_id: int, db: Session = Depends(get_db)): user = db.get(User, user_id) return UserResponse( id=user.id, email=user.email, display_name=user.name or user.email.split("@")[0], avatar_url=f"https://avatars.example.com/{user.id}.png", ) ``` Explicit conversion when fi