Plan and build production-ready FastAPI endpoints with async SQLAlchemy, Pydantic v2 models, dependency injection for auth, and pytest tests. Uses interview-driven planning to clarify data models, authentication method, pagination strategy, and caching before writing any code.
Plan and build production-ready FastAPI endpoints with async SQLAlchemy, Pydantic v2 models, dependency injection for auth, and pytest tests. Uses interview-driven planning to clarify data models, authentication method, pagination strategy, and caching before writing any code.
Add new API endpoints to an existing FastAPI project
Build CRUD operations with proper validation and error handling
Set up authenticated endpoints with dependency injection
Create async database queries with SQLAlchemy 2.0
Generate complete test coverage for API routes
Phase 1: Explore (Plan Mode)
Enter plan mode. Before writing any code, explore the existing project to understand:
Project structure
Find the FastAPI app entry point (main.py, app.py, or app/__init__.py)
Identify the router organization pattern (single file vs routers/ directory)
Check for existing models/, schemas/, crud/, or services/ directories
Look at pyproject.toml or requirements.txt for installed dependencies
Existing patterns
How are existing endpoints structured? (function-based vs class-based)
What ORM is used? (SQLAlchemy 2.0 async, Tortoise, raw SQL, none)
How is the database session managed? (Depends(get_db), middleware, other)
What auth pattern exists? (OAuth2PasswordBearer, API key header, custom)
Are there existing Pydantic base models or shared schemas?
What response format is standard? (direct model, wrapped {"data": ..., "meta": ...})
Test patterns
Where do tests live? (tests/, test_*.py, *_test.py)
What test client is used? (httpx AsyncClient, TestClient, pytest-asyncio)
Are there test fixtures for database and auth?
Phase 2: Interview (AskUserQuestion)
Use AskUserQuestion to clarify requirements. Ask in rounds — do NOT dump all questions at once.
Round 1: Core endpoint
Question: "What resource does this endpoint manage?"
Header: "Resource"
Options:
- "New resource (I'll describe the fields)" — Creating a new data model from scratch
- "Existing model (extend it)" — Adding endpoints for a model that already exists in the codebase
- "Relationship endpoint (nested)" — e.g., /users/{id}/orders — endpoint on a related resource
Question: "Which HTTP methods do you need?"
Header: "Methods"
multiSelect: true
Options:
- "Full CRUD (GET list, GET detail, POST, PUT/PATCH, DELETE)" — All standard operations
- "Read-only (GET list + GET detail)" — No mutations
- "Custom action (POST /resource/{id}/action)" — Business logic endpoint, not standard CRUD
Round 2: Data model (if new resource)
Question: "What fields does the resource have? (describe briefly)"
Header: "Fields"
Options:
- "Simple (< 6 fields, basic types)" — Strings, ints, booleans, dates
- "Medium (6-15 fields, some relations)" — Includes foreign keys or enums
- "Complex (nested objects, polymorphic)" — JSON fields, discriminated unions, computed fields
Round 3: Auth and access control
Question: "How should this endpoint be authenticated?"
Header: "Auth"
Options:
- "JWT Bearer token (Recommended)" — OAuth2PasswordBearer with JWT decode
- "API Key header" — X-API-Key header validation
- "No auth (public)" — Open endpoint, no authentication required
- "Use existing auth" — Reuse the auth dependency already in the project
Question: "Do you need role-based access control?"
Header: "RBAC"
Options:
- "No — any authenticated user" — Single permission level
- "Yes — role check (admin, user, etc.)" — Require specific roles per endpoint
- "Yes — ownership check" — Users can only access their own resources
Round 4: Pagination, filtering, caching
Question: "What pagination style for list endpoints?"
Header: "Pagination"
Options:
- "Cursor-based (Recommended)" — Best for real-time data, no offset drift
- "Offset/limit" — Simple, good for admin panels with page numbers
- "No pagination" — Small datasets, return all results
Question: "Do you need response caching?"
Header: "Caching"
Options:
- "No caching" — Fresh data on every request
- "Cache-Control headers" — Client-side caching via HTTP headers
- "Redis/in-memory cache" — Server-side caching with TTL
Phase 3: Plan (ExitPlanMode)
Write a concrete implementation plan covering:
Files to create/modify — exact paths based on project structure discovered in Phase 1
Pydantic schemas — Create, Update, Response, and List schemas with field types
SQLAlchemy model — table name, columns, relationships, indexes
CRUD/service layer — async functions for each operation
Router — endpoint signatures, status codes, response models
Always use FastAPI's HTTPException with consistent detail messages. For validation errors, Pydantic v2 handles them automatically via RequestValidationError (422).
# 404 — not foundraise HTTPException(status_code=404, detail="Resource not found")
# 409 — conflict (duplicate)raise HTTPException(status_code=409, detail="Resource with this name already exists")
# 403 — forbiddenraise HTTPException(status_code=403, detail="Not allowed to modify this resource")
Checklist before finishing
All endpoints return proper status codes (201 for POST, 204 for DELETE)
Pydantic schemas use model_config = ConfigDict(from_attributes=True) for ORM mode
List endpoint has pagination with configurable limit
Auth dependency is applied to all non-public endpoints
Tests cover: happy path, not found, unauthorized, validation errors
Router is registered in the main FastAPI app
Database model has proper indexes on filtered/sorted columns
