fastapi-backend_skill

Overview

This skill packages patterns and code for building production-grade FastAPI backends with SQLModel, Pydantic v2, and JWT/JWKS authentication. It focuses on REST CRUD endpoints, Neon PostgreSQL integration, Better Auth JWKS verification, audit logging, and OpenAPI-ready documentation. Use it to accelerate secure, maintainable API development with human-agent parity.

How this skill works

The skill provides schemas (SQLModel) that serve as both database and API contracts, a Neon-compatible database connection helper, and reusable CRUD endpoints. It includes an async-safe transaction pattern, JWKS-backed JWT verification with caching, audit logging utilities, and examples that add an "Authorize" button to Swagger UI. Patterns emphasize extracting primitives before commits, avoiding internal commits in services, and designing endpoints usable by CLI, agents, and web clients.

When to use it

• Building REST APIs with FastAPI and SQLModel
• Connecting to Neon PostgreSQL and running safe async transactions
• Implementing JWT verification against a Better Auth JWKS endpoint
• Creating CRUD endpoints with audit logging and OpenAPI docs
• Designing endpoints for both human and agent (MCP/CLI) clients

Best practices

• Keep models split: table=True for DB models and separate request/response models for API shape
• Use a cached JWKS fetch with a TTL and verify tokens by matching kid to key
• Extract primitive values (IDs, timestamps) before commit/refresh to avoid detached-object errors in async sessions
• Let callers own transactions: service helpers should add to the session but not commit
• Limit query results with offset/limit and expose filters explicitly to protect DB performance

Example use cases

• Task management API with endpoints to create, list, update, start, progress, and complete tasks
• Neon-hosted backend where SQLModel maps to PostgreSQL tables and AsyncSession patterns prevent MissingGreenlet errors
• Secure APIs that verify JWTs using Better Auth JWKS and expose an Authorize button in Swagger UI
• Audit trail capture for every state change, storing actor type (human or agent) and context JSON
• Shared endpoints that work for web UI, CLI tools, and agent/MCP clients without changing contracts