fastapi
Build and test FastAPI services with Pydantic models, dependency injection, async routes, OpenAPI, and authentication hooks.
SKILL.mdskills/fastapi/SKILL.md
GitHubFastAPI 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
BackgroundTasksalone. - Team standard is Django ORM/admin—don't force FastAPI for CRUD admin.
Operational Capabilities & Agent Directives
- Request + response models on public routes; avoid bare
dictresponses. APIRouterper domain with shared exception handlers.- Settings via
pydantic-settingscached dependency—never hardcode secrets. - Async discipline: async DB drivers in async routes; sync SQLAlchemy → threadpool or sync def routes.
- Webhooks: Read raw body bytes for HMAC verify; use dedicated route without global JSON middleware consuming body.
- Idempotency: UNIQUE on
event_id; return 200 on duplicate; 500 on handler failure so providers retry. - 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())
Stripe webhook (raw body):
@app.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
payload = await request.body()
sig = request.headers.get("stripe-signature", "")
event = stripe.Webhook.construct_event(payload, sig, settings.stripe_webhook_secret)
# idempotency gate on event.id
Technical Troubleshooting Matrix
| Issue | Root cause | Fix |
|---|---|---|
| Signature verify fails | Body parsed/re-serialized | Use raw request.body() |
| Event loop blocked | Sync DB in async def |
Threadpool or sync route |
| 422 on valid JSON | Pydantic v2 strict extras | Align models; model_config |
| OpenAPI drift | Missing response_model |
Declare response types |
| Duplicate fulfillment | No idempotency store | UNIQUE event_id + txn |
Best practices
- Central
@app.exception_handlerfor domain errors. - Correct HTTP semantics: 201 create, 204 delete, 409 conflict.
- Version external APIs (
/v1). - Structured logs with
request_idmiddleware. TestClientor httpx ASGI transport for integration tests.
Limitations
BackgroundTasks≠ durable queue (use Celery, ARQ, Temporal).- WebSockets need explicit patterns.
- Migrations (Alembic) are separate from FastAPI.
Related skills
@stripe— payment events and idempotency@postgresql— transactional fulfillment@docker— multi-worker uvicorn/gunicorn@nodejs— compare Express webhook raw body patterns
Agent Operational Directive
MANDATORY: Verify webhook signatures on untouched raw bytes. Persist provider event IDs before side effects. Never block async routes with sync DB without an explicit threadpool strategy. Load secrets from environment only.
Sources
- FastAPI docs
- Stripe webhook signatures (Python)
- Idempotency patterns for Stripe webhooks (transaction + UNIQUE event_id)