Recap — The FastAPI Mental Model

# The FastAPI Mental Model FastAPI is the dominant Python web framework in 2026 for new APIs. Built on Starlette + Pydantic; type-hint-first; async-first; auto-generates OpenAPI docs. ## Why FastAPI Compared to alternatives: - **Flask**: older, simpler, more flexible, less typed, no async-first. - **Django**: full-stack (ORM, admin, templates); heavy for pure APIs. - **Starlette**: FastAPI's underlying lower-level framework. - **Tornado / aiohttp**: older async frameworks; smaller communities now. FastAPI's strengths: - Type hints become validation + docs (automatic). - Async-first; great for I/O-heavy APIs. - Pydantic integration (models for input/output). - Speed (comparable to Node.js/Go for I/O work). - Dev experience (auto-reload, OpenAPI UI at /docs). ## Hello World ```python # main.py from fastapi import FastAPI app = FastAPI() @app.get("/") def root(): return {"message": "Hello, world"} ``` Run: ```bash pip install fastapi uvicorn uvicorn main:app --reload ``` Browse: - http://localhost:8000 → `{"message": "Hello, world"}` - http://localhost:8000/docs → interactive OpenAPI UI (Swagger) - http://localhost:8000/redoc → alternative docs Auto-generated docs are FastAPI's killer feature. ## Routes ```python @app.get("/users") def list_users(): ... @app.post("/users") def create_user(): ... @app.put("/users/{user_id}") def update_user(user_id: int): ... @app.delete("/users/{user_id}") def delete_user(user_id: int): ... ``` HTTP methods as decorators. Path params in `{}`. ## Path parameters ```python @app.get("/users/{user_id}") def get_user(user_id: int): return {"user_id": user_id} ``` Type annotation (`int`) → automatic validation. If client sends `/users/abc`, FastAPI returns 422 with clear error. ## Query parameters Parameters not in the path become query params: ```python @app.get("/users") def list_users(limit: int = 10, offset: int = 0, search: str | None = None): ... ``` Call: `/users?limit=20&offset=40&search=alice`. Defaults make them optional; required if no default. ## Request body For POST/PUT, use Pydantic models: ```python from pydantic import BaseModel class UserCreate(BaseModel): name: str email: str age: int @app.post("/users") def create_user(payload: UserCreate): return {"name": payload.name, ...} ``` FastAPI: - Parses JSON body. - Validates against the model. - Returns 422 with details if invalid. ## Response models ```python class UserResponse(BaseModel): id: int name: str email: str @app.post("/users", response_model=UserResponse) def create_user(payload: UserCreate) -> UserResponse: new_user = save_to_db(payload) return UserResponse(id=new_user.id, name=new_user.name, email=new_user.email) ``` Why use `response_model`: - Filters output (extra fields stripped). - Documents schema in OpenAPI. - Validates output (catches bugs). ## Status codes ```python from fastapi import status @app.post("/users", status_code=status.HTTP_201_CREATED) def create_user(...): ... ``` For errors: ```python from fastapi import HTTPException @app.get("/users/{user_id}") def get_user(user_id: int): user = db.get(user_id) if not user: raise HTTPException(404, detail="User not found") return user ``` `HTTPException` short-circuits to the framework's error handler. ## File structure For tiny apps: ``` main.py # all routes ``` For real apps: ``` src/my_api/ ├── main.py # FastAPI app + middleware ├── routers/ │ ├── users.py # user-related routes │ └── orders.py ├── models.py # SQLAlchemy ├── schemas.py # Pydantic ├── deps.py # dependency providers └── config.py # settings ``` Routers organize endpoints: ```python # routers/users.py from fastapi import APIRouter router = APIRouter(prefix="/users", tags=["users"]) @router.get("/{user_id}") def get_user(user_id: int): ... # main.py from routers import users app.include_router(users.router) ``` ## Tags Group endpoints in docs: ```python @app.post("/users", tags=["users"]) def create_user(): ... ``` OpenAPI UI shows endpoints grouped by tag. ## Common FastAPI mistakes 1. **Using sync functions for I/O-heavy endpoints.** Slower than async. 2. **Using async functions but calling sync I/O inside.** Defeats async. 3. **No response_model.** Exposes more fields than intended. 4. **Mixing Pydantic and SQLAlchemy models.** Returning ORM directly leaks internal fields. 5. **HTTPException catches all errors.** Use specific exceptions and exception handlers. ## Takeaway FastAPI: routes with HTTP-method decorators; type hints become validation; Pydantic for body/response; automatic OpenAPI docs at /docs. Path params in URL, query params as function args, body as Pydantic model. `response_model` for output filtering and documentation. `HTTPException` for error responses. For real apps: routers in separate files + structured project layout. Async support: opt-in via `async def`.