fastapi

FastAPI Python APIs AI Skill Guide (Claude)

Overview & Engine Architecture

FastAPI builds HTTP APIs on Starlette with Pydantic validation and automatic OpenAPI. Dependencies inject auth, DB sessions, and settings. Async routes must not block the event loop with sync ORM/socket calls without run_in_threadpool.

Claude operates as a Principal API Engineer: typed I/O, webhook raw bodies, idempotent event processing, and consistent error envelopes.

uvicorn / gunicorn workers
        │
     FastAPI app
   ├── APIRouter (domain modules)
   ├── Depends() graph
   ├── Pydantic request/response models
   └── /docs OpenAPI

---

When to use / when not to

Use when

• High-throughput JSON APIs with automatic schema docs.
• Webhook receivers (Stripe, GitHub) with signature verification.
• Internal microservices where Python ecosystem fits.

Do not use when

• Heavy CPU work belongs in a queue worker—not BackgroundTasks alone.
• Team standard is Django ORM/admin—don't force FastAPI for CRUD admin.

---

Operational Capabilities & Agent Directives

1. Request + response models on public routes; avoid bare dict responses.
2. APIRouter per domain with shared exception handlers.
3. Settings via pydantic-settings cached dependency—never hardcode secrets.
4. Async discipline: async DB drivers in async routes; sync SQLAlchemy → threadpool or sync def routes.
5. Webhooks: Read raw body bytes for HMAC verify; use dedicated route without global JSON middleware consuming body.
6. Idempotency: UNIQUE on event_id; return 200 on duplicate; 500 on handler failure so providers retry.
7. CORS: Explicit origins—never * with credentials.

---

App sketch

from fastapi import Depends, FastAPI, HTTPException, Request
from pydantic import BaseModel, Field

app = FastAPI(title="Inventory API", version="1.2.0")

class ItemIn(BaseModel):
    sku: str = Field(min_length=1, max_length=64)
    qty: int = Field(ge=0)

class ItemOut(ItemIn):
    id: int

def get_current_user(authorization: str | None = None) -> str:
    if not authorization:
        raise HTTPException(status_code=401, detail="unauthorized")
    return "user"

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(body: ItemIn, user: str = Depends(get_current_user)) -> ItemOut:
    return ItemOut(id=1, **body.model_dump())