FastAPI Skill

Production-tested patterns for FastAPI with Pydantic v2.

Versions (verified January 2026): FastAPI 0.128.0, Pydantic 2.11.7, SQLAlchemy 2.0.30, Uvicorn 0.35.0

Critical Rules

Always Do

1. Separate Pydantic schemas from SQLAlchemy models
2. Use async for I/O operations
3. Validate with Pydantic Field()
4. Use dependency injection via Depends()
5. Return proper status codes (201 create, 204 delete)

Never Do

1. Never use blocking calls in async routes (no time.sleep())
2. Never put business logic in routes (use service layer)
3. Never hardcode secrets
4. Never skip validation
5. Never use * in CORS origins for production

7 Known Issues

Resume Matcher Specific

• Type hints on ALL functions (non-negotiable)
• copy.deepcopy() for mutable defaults
• Log errors server-side, generic messages to clients
• API keys via api_key= parameter, not os.environ
• Project uses TinyDB (JSON file storage), not SQLAlchemy

Common Error Fixes

422 Unprocessable Entity

Check /docs endpoint, verify JSON matches schema, check required vs optional fields.

CORS Errors

app.add_middleware(CORSMiddleware, allow_origins=["http://localhost:3000"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"])

Async Blocking

Use async def + await for I/O. Use plain def for CPU-bound (runs in thread pool). Use run_in_executor for blocking calls in async routes.

Full Reference

Complete skill with all code examples: .claude/skills/fastapi/SKILL.md