Python API Design (FastAPI)
Overview
Keep the FastAPI app small and testable. Build with create_app() so pytest can
use TestClient without starting a real server on a fixed port.
Process
- Register routes on the app from
create_app()inapp/main.py. - Use Pydantic models for request/response bodies when shapes matter.
- Return correct status codes; use
HTTPExceptionfor client errors. - Add a pytest case for each new route or behavior change.
- Run
pytestbefore claiming completion.
Project Layout
app/main.py—create_app()factory and route definitionstests/— pytest tests usingfastapi.testclient.TestClientrequirements.txt— pinned runtime + test dependencies
Testing
pythonfrom fastapi.testclient import TestClient from app.main import create_app def test_health(): client = TestClient(create_app()) assert client.get("/api/health").json() == {"status": "ok"}
Guidelines
- Type hints on route functions and shared helpers.
- Secrets from environment variables (
os.environ), never hardcoded. - Keep route handlers thin; extract logic to pure functions when non-trivial.
- Prefer dependency injection for DB sessions and auth when the app grows.
Anti-patterns
- Business logic embedded directly in route decorators without tests.
- Returning raw exception strings to clients in production.
- Skipping tests because "FastAPI validates for us" — test behavior, not just schemas.
