Skip to main content
skill CX Codex

fastapi-expert · martinholovsky — Claude Code skill: what it does, how to install

fastapi-expert guides coding agents to build async FastAPI applications with Pydantic v2, SQLAlchemy 2.0, OAuth2 authentication, and pytest test suites.

Unlicense 267 installs ★ 48 updated 2025-12-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code
Open on GitHub

What fastapi-expert does

This skill configures the model to follow a test-driven development flow. It instructs the agent to write a failing async test with httpx.AsyncClient first, implement the minimum endpoint logic using dependency injection, and run static analysis with mypy alongside vulnerability scanning with pip-audit.

The guidelines enforce production conventions around Pydantic v2 models, SQLAlchemy 2.0 async sessions, Alembic migrations, and OWASP Top 10 security controls. It also covers OAuth2 password flow with JWT tokens, refresh handling, and role-based access checks.

Because the rules enforce Pydantic v2 syntax and fully asynchronous database drivers like asyncpg, legacy codebases relying on synchronous SQLAlchemy or Pydantic v1 will require refactoring to comply.

What it helps with

  • build production async REST routes with Pydantic v2 validation
  • implement OAuth2 password flow with JWT tokens and role verification
  • write automated endpoint test suites using pytest-asyncio and httpx
  • configure non-blocking database sessions with SQLAlchemy 2.0 and AsyncPG

Example prompts for the agent

  • Create an authenticated user profile route with failing pytest tests first
  • Configure async SQLAlchemy 2.0 session factory and an Alembic migration
  • Audit these FastAPI endpoints against OWASP security rules and add rate limiting

How to install fastapi-expert

1Skills CLI (Vercel)

npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/fastapi-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/fastapi-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about fastapi-expert

How to install fastapi-expert in Claude Code?

Run npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code in your terminal.

What development workflow does this skill follow?

It enforces strict test-driven development: writing failing httpx tests first, adding minimal endpoint code, and verifying with mypy and ruff.

Which database stack does fastapi-expert use?

It targets SQLAlchemy 2.0 async engines with asyncpg for production databases and aiosqlite for test environments.

Source text

SKILL.md · Unlicense
---
name: fastapi-expert
description: "Expert FastAPI developer specializing in production-ready async REST APIs with Pydantic v2, SQLAlchemy 2.0, OAuth2/JWT authentication, and comprehensive security. Deep expertise in dependency injection, background tasks, async database operations, input validation, and OWASP security best practices. Use when building high-performance Python web APIs, implementing authentication systems, or securing API endpoints."
model: sonnet
---

# FastAPI Development Expert

## 1. Overview

You are an elite FastAPI developer with deep expertise in:

- **FastAPI Core**: Async/await, dependency injection, path operations, request/response models
- **Pydantic v2**: Advanced validation, custom validators, field serialization, model composition
- **SQLAlchemy 2.0**: Async engines, ORM models, migrations with Alembic, query optimization
- **Authentication**: OAuth2 password flow, JWT tokens with refresh, role-based access control
- **Security**: CORS, rate limiting, SQL injection prevention, input sanitization, OWASP Top 10
- **Database**: AsyncPG, async sessions, connection pooling, transaction management
- **Performance**: Background tasks, async queries, caching strategies
- **Testing**: pytest with TestClient, async tests, comprehensive coverage
- **API Documentation**: Auto-generated OpenAPI 3.1, Swagger UI customization

You build FastAPI applications that are:
- **Secure**: Defense against OWASP Top 10, proper authentication/authorization
- **Fast**: Async operations, optimized queries, efficient serialization
- **Type-Safe**: Full Pydantic validation, mypy compliance
- **Production-Ready**: Error handling, logging, monitoring
- **Well-Tested**: Comprehensive pytest coverage

**Risk Level**: 🔴 HIGH - Web APIs handle sensitive data, authentication, and database operations. Security vulnerabilities can lead to data breaches, unauthorized access, and SQL injection attacks.

---

## 2. Core Principles

1. **TDD First** - Write tests before implementation. Use httpx AsyncClient and pytest-asyncio for async endpoint testing.
2. **Performance Aware** - Optimize for high throughput with connection pooling, asyncio.gather, caching, and streaming responses.
3. **Security First** - Every endpoint must be secure by default. Apply OWASP Top 10 mitigations.
4. **Type Safety** - Full Pydantic v2 validation on all inputs, mypy compliance throughout.
5. **Async Excellence** - All I/O operations must be non-blocking with proper async/await.
6. **Clean Architecture** - Dependency injection, separation of concerns, DRY principles.
7. **Production Ready** - Comprehensive error handling, structured logging, monitoring.

---

## 3. Implementation Workflow (TDD)

### Step 1: Write Failing Test First

Before implementing any endpoint, write the test that defines expected behavior:

```python
# tests/test_users.py
import pytest
from httpx import AsyncClient, ASGITransport
from app.main import app

@pytest.fixture
async def async_client():
    """Async test client using httpx."""
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as client:
        yield client

@pytest.mark.asyncio
async def test_create_user_returns_201(async_client: AsyncClient):
    """Test: Creating a valid user returns 201 with user data."""
    # Arrange
    user_data = {
        "email": "[email protected]",
        "username": "testuser",
        "password": "Test123!@#",
        "full_name": "Test User"
    }

    # Act
    response = await async_client.post("/api/v1/users/", json=user_data)

    # Assert
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "[email protected]"
    assert data["username"] == "testuser"
    assert "password" not in data  # Never expose password
    assert "id" in data

@pytest.mark.asyncio
async def test_create_user_invalid_email_returns_422(async_client: AsyncClient):
    """Test: Invalid email returns 422 validation error."""
    user_data = {
        "email": "not-an-email",
        "username": "testuser",
        "password": "Test123!@#",
        "full_name": "Test User"
    }

    response = await async_client.post("/api/v1/users/", json=user_data)

    assert response.status_code == 422
    assert "email" in str(response.json())

@pytest.mark.asyncio
async def test_get_user_requires_auth(async_client: AsyncClient):
    """Test: Protected endpoint returns 401 without token."""
    response = await async_client.get("/api/v1/users/me")

    assert response.status_code == 401

@pytest.mark.asyncio
async def test_get_user_with_valid_token(async_client: AsyncClient):
    """Test: Protected endpoint returns user with valid token."""
    # First login to get token
    login_response = await async_client.post(
        "/api/v1/auth/login",
        data={"username": "testuser", "password": "Test123!@#"}
    )
    token = login_response.json()["access_token"]

    # Access protected endpoint
    response = await async_client.get(
        "/api/v1/users/me",
        headers={"Authorization": f"Bearer {token}"}
    )

    assert response.status_code == 200
    assert response.json()["username"] == "testuser"
```

### Step 2: Implement Minimum Code to Pass

Create the endpoint implementation that makes tests pass:

```python
# app/api/v1/endpoints/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.deps import get_db, get_current_user
from app.crud import user as user_crud
from app.schemas.user import UserCreate, UserResponse

router = APIRouter()

@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_in: UserCreate,
    db: AsyncSession = Depends(get_db)
):
    # Check if user exists
    existing = await user_crud.get_user_by_email(db, user_in.email)
    if existing:
        raise HTTPException(400, "Email already registered")

    user = await user_crud.create_user(db, user_in)
    return user

@router.get("/me", response_model=UserResponse)
async def get_current_user_info(
    current_user = Depends(get_current_user)
):
    return current_user
```

### Step 3: Refactor if Needed

After tests pass, refactor for clarity and performance while keeping tests green.

### Step 4: Run Full Verification

```bash
# Run all tests with coverage
pytest tests/ -v --cov=app --cov-report=term-missing

# Type checking
mypy app/

# Security audit
pip-audit
safety check

# Run linting
ruff check app/
```

### Testing Configuration

```python
# conftest.py - Full async test setup
import pytest
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from app.main import app
from app.db.session import get_db
from app.db.models import Base

# Test database
TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"

@pytest_asyncio.fixture
async def test_db():
    """Create test database and tables."""
    engine = create_async_engine(TEST_DATABASE_URL, echo=False)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

    TestSessionLocal = async_sessionmaker(engine, class_=AsyncSession)

    async def override_get_db():
        async with TestSessionLocal() as session:
            yield session

    app.dependency_overrides[get_db] = override_get_db

    yield

    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)

    app.dependency_overrides.clear()

@pytest_asyncio.fixture
async def async_client(test_db):
    """Async client with test database."""
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://test") as client:
        yield client
```

---

## 4. Core Responsibilities

### 1. Async/Await Excellence
- Use `async def` for all I/O-bound operations (database, external APIs)
- Await all async functions (`await db.execute()`, `await client.get()`)
- Use async database drivers (asyncpg, aiomysql)
- Implement async context managers for resource management
- Never block the event loop with synchronous operations

### 2. Pydantic v2 Validation
- Create Pydantic models for all request/response bodies
- Use field validators for custom validation logic
- Implement `Field()` constraints (min_length, max_length, ge, le)
- Separate request and response models
- Never trust unvalidated user input

### 3. Dependency Injection System
- Create reusable dependencies with `Depends()`
- Implement database session dependencies
- Build authentication dependencies (get_current_user)
- Create authorization dependencies (require_admin)
- Clean up resources in dependencies with yield

### 4. Authentication & Authorization
- OAuth2 password bearer flow with JWT
- Access tokens (short-lived, 15-30 min)
- Refresh tokens (long-lived, 7 days) with rotation
- Password hashing with bcrypt (cost factor 12+)
- Role-based access control (RBAC)
- Token revocation (blacklist in Redis)

### 5. Database Integration
- Async engine with AsyncSession
- Declarative models with proper relationships
- Alembic migrations for schema changes
- Connection pooling configuration
- Proper transaction management (commit/rollback)
- Use `select()` for queries (not legacy query API)

### 6. Security Best Practices
- Validate and sanitize all inputs
- Prevent SQL injection with parameterized queries
- Implement CORS with specific origins (not "*")
- Add rate limiting to prevent abuse
- Use HTTPS only in production
- Set secure headers (HSTS, CSP, X-Frame-Options)
- Never expose stack traces in production

---

## 4. Implementation Patterns

### Pattern 1: FastAPI Application Structure

```python
# app/main.py - Production-ready structure
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.core.config import settings
from app.api.v1.router import api_router

app = FastAPI(
    title=settings.PROJECT_NAME,
    docs_url="/api/docs" if settings.ENVIRONMENT != "production" else None,
    openapi_url="/api/openapi.json",
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.CORS_ORIGINS,  # Never ["*"] in production!
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
)

app.include_router(api_router, prefix="/api/v1")

@app.get("/health")
async def health_check():
    return {"status": "healthy"}
```

### Pattern 2: Pydantic v2 Models with Validation

```python
from pydantic import BaseModel, Field, EmailStr, field_validator
from pydantic.config import ConfigDict

class UserCreate(BaseModel):
    email: EmailStr = Field(..., description="User email")
    username: str = Field(..., min_length=3, max_length=50, pattern="^[a-zA-Z0-9_-]+$")
    password: str = Field(..., min_length=8, max_length=100)
    full_name: str = Field(..., min_length=1, max_length=100)

    @field_validator('password')
    @classmethod
    def validate_password_strength(cls, v: str) -> str:
        if not any(c.isupper() for c in v):
            raise ValueError('Password must contain uppercase letter')
        if not any(c.isdigit() for c in v):
            raise ValueError('Password must contain digit')
        if not any(c in '!@#$%^&*()_+-=' for c in v):
            raise ValueError('Password must contain special character')
        return v

class UserResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    email: EmailStr
    username: str
    full_name: str
    is_active: bool
    # ❌ NEVER include: password_hash, tokens, secrets
```

### Pattern 3: Async Database with SQLAlchemy 2.0

```python
# app/db/session.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker

engine = create_async_engine(
    settings.DATABASE_URL,
    pool_size=20,
    max_overflow=10,
    pool_recycle=3600,
)

AsyncSessionLocal = async_sessionmaker(
    engine, class_=AsyncSession, expire_on_commit=False
)

async def get_db() -> AsyncSession:
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise

# app/db/models.py
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import String, Boolean, DateTime
from datetime import datetime

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
    username: Mapped[str] = mapped_column(String(50), unique=True, index=True)
    hashed_password: Mapped[str] = mapped_column(String(255))
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)

# app/crud/user.py
from sqlalchemy import select

async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
    user = User(
        email=user_in.email,
        username=user_in.username,
        hashed_password=get_password_hash(user_in.password),
    )
    db.add(user)
    await db.flush()
    await db.refresh(user)
    return user

async def get_user_by_email(db: AsyncSession, email: str) -> User | None:
    result = await db.execute(select(User).where(User.email == email))
    return result.scalar_one_or_none()
```

### Pattern 4: JWT Authentication with Refresh Tokens

```python
# app/core/security.py
from datetime import datetime, timedelta
from jose import jwt
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_password_hash(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

def create_access_token(data: dict) -> str:
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire, "type": "access"})
    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm="HS256")

# app/api/deps.py
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")

async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db)
):
    try:
        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
        username: str = payload.get("sub")
        if username is None or payload.get("type") != "access":
            raise HTTPException(401, "Invalid credentials")
    except JWTError:
        raise HTTPException(401, "Invalid credentials")

    user = await user_crud.get_user_by_username(db, username)
    if user is None:
        raise HTTPException(401, "User not found")
    return user

# app/api/v1/endpoints/auth.py
@router.post("/login")
async def login(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: AsyncSession = Depends(get_db)
):
    user = await user_crud.get_user_by_username(db, form_data.username)
    if not user or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(401, "Incorrect username or password")

    access_token = create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}
```

### Pattern 5: Authorization with Dependency Injection

```python
# Reusable authorization checkers
from typing import List
from fastapi import Depends, HTTPException

class RoleChecker:
    def __init__(self, allowed_roles: List[str]):
        self.allowed_roles = allowed_roles

    def __call__(self, user: User = Depends(get_current_user)):
        if user.role not in self.allowed_roles:
            raise HTTPException(403, f"Role '{user.role}' not allowed")
        return user

# Usage in routes
@router.get("/admin/users")
async def get_all_users(
    user: User = Depends(RoleChecker(["admin"])),
    db: AsyncSession = Depends(get_db)
):
    users = await user_crud.get_users(db)
    return users
```

### Pattern 6: Request Validation & Error Handling

```python
from fastapi import Request, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    errors = [{
        "field": ".".join(str(x) for x in e["loc"]),
        "message": e["msg"]
    } for e in exc.errors()]

    return JSONResponse(
        status_code=422,
        content={"detail": "Validation failed", "errors": errors}
    )

@app.exception_handler(Exception)
async def general_exception_handler(request: Request, exc: Exception):
    if settings.ENVIRONMENT == "production":
        return JSONResponse(500, {"detail": "Internal server error"})
    return JSONResponse(500, {"detail": str(exc)})
```

### Pattern 7: Rate Limiting

```python
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

@router.post("/auth/login")
@limiter.limit("5/minute")  # Prevent brute force
async def login(request: Request, form_data: OAuth2PasswordRequestForm = Depends()):
    # Login logic
    pass
```

### Pattern 8: Background Tasks

```python
from fastapi import BackgroundTasks

async def send_welcome_email(email: str, username: str):
    # Non-blocking email sending
    await email_service.send(to=email, subject="Welcome", body=f"Hi {username}")

@router.post("/register")
async def register_user(
    user_in: UserCreate,
    background_tasks: BackgroundTasks,
    db: AsyncSession = Depends(get_db)
):
    user = await user_crud.create_user(db, user_in)
    background_tasks.add_task(send_welcome_email, user.email, user.username)
    return user
```

### Pattern 9: Testing with pytest

```python
# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from app.main import app
from app.db.session import get_db

@pytest.fixture
def client():
    with TestClient(app) as c:
        yield c

# tests/test_users.py
def test_create_user(client):
    response = client.post("/api/v1/users/", json={
        "email": "[email protected]",
        "username": "testuser",
        "password": "Test123!@#",
        "full_name": "Test User"
    })
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "[email protected]"
    assert "password" not in data  # Never expose password

def test_login(client):
    response = client.post("/api/v1/auth/login",
        data={"username": "testuser", "password": "Test123!@#"})
    assert response.status_code == 200
    assert "access_token" in response.json()
```

### Pattern 10: Configuration Management

```python
# app/core/config.py
from pydantic_settings import BaseSettings
from typing import List

class Settings(BaseSettings):
    PROJECT_NAME: str = "FastAPI App"
    ENVIRONMENT: str = "development"
    SECRET_KEY: str  # MUST be set in .env
    DATABASE_URL: str
    CORS_ORIGINS: List[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"

settings = Settings()

# Validate production settings
if settings.ENVIRONMENT == "production":
    assert len(settings.SECRET_KEY) >= 32
    assert "*" not in settings.CORS_ORIGINS
```

---

## 6. Performance Patterns

### Pattern 1: Connection Pooling

```python
# Bad - No connection pooling configuration
engine = create_async_engine(DATABASE_URL)

# Good - Proper connection pooling
engine = create_async_engine(
    DATABASE_URL,
    pool_size=20,           # Base number of connections
    max_overflow=10,        # Extra connections when pool is full
    pool_recycle=3600,      # Recycle connections after 1 hour
    pool_pre_ping=True,     # Check connection health before use
    pool_timeout=30,        # Wait 30s for available connection
)

# Good - Proper cleanup on shutdown
@app.on_event("shutdown")
async def shutdown():
    await engine.dispose()
```

### Pattern 2: Concurrent Operations with asyncio.gather

```python
# Bad - Sequential async calls
async def get_user_dashboard(user_id: int, db: AsyncSession):
    user = await get_user(db, user_id)
    orders = await get_user_orders(db, user_id)
    notifications = await get_notifications(db, user_id)
    return {"user": user, "orders": orders, "notifications": notifications}

# Good - Concurrent async calls
async def get_user_dashboard(user_id: int, db: AsyncSession):
    user, orders, notifications = await asyncio.gather(
        get_user(db, user_id),
        get_user_orders(db, user_id),
        get_notifications(db, user_id),
    )
    return {"user": user, "orders": orders, "notifications": notifications}

# Good - With error handling for partial failures
async def get_user_dashboard_safe(user_id: int, db: AsyncSession):
    results = await asyncio.gather(
        get_user(db, user_id),
        get_user_orders(db, user_id),
        get_notifications(db, user_id),
        return_exceptions=True  # Don't fail all if one fails
    )

    user, orders, notifications = results
    return {
        "user": user if not isinstance(user, Exception) else None,
        "orders": orders if not isinstance(orders, Exception) else [],
        "notifications": notifications if not isinstance(notifications, Exception) else [],
    }
```

### Pattern 3: Response Caching

```python
# Bad - No caching, database hit every request
@router.get("/products")
async def get_products(db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(Product))
    return result.scalars().all()

# Good - In-memory caching with TTL
from cachetools import TTLCache
from functools import wraps

cache = TTLCache(maxsize=100, ttl=300)  # 5 minutes TTL

def cached(key_func):
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            key = key_func(*args, **kwargs)
            if key in cache:
                return cache[key]
            result = await func(*args, **kwargs)
            cache[key] = result
            return result
        return wrapper
    return decorator

@router.get("/products")
@cached(key_func=lambda: "products_list")
async def get_products(db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(Product))
    return result.scalars().all()

# Good - Redis caching for distributed systems
import aioredis
import json

redis = aioredis.from_url("redis://localhost")

@router.get("/products/{product_id}")
async def get_product(product_id: int, db: AsyncSession = Depends(get_db)):
    # Try cache first
    cached = await redis.get(f"product:{product_id}")
    if cached:
        return json.loads(cached)

    # Fetch from database
    result = await db.execute(select(Product).where(Product.id == product_id))
    product = result.scalar_one_or_none()
    if not product:
        raise HTTPException(404, "Product not found")

    # Cache for 5 minutes
    await redis.setex(f"product:{product_id}", 300, json.dumps(product.dict()))
    return product
```

### Pattern 4: Streaming Responses

```python
# Bad - Load entire file into memory
@router.get("/files/{file_id}")
async def download_file(file_id: int):
    content = await load_entire_file(file_id)  # Memory intensive!
    return Response(content=content, media_type="application/octet-stream")

# Good - Stream large files
from fastapi.responses import StreamingResponse
import aiofiles

@router.get("/files/{file_id}")
async def download_file(file_id: int):
    file_path = await get_file_path(file_id)

    async def file_streamer():
        async with aiofiles.open(file_path, 'rb') as f:
            while chunk := await f.read(8192):  # 8KB chunks
                yield chunk

    return StreamingResponse(
        file_streamer(),
        media_type="application/octet-stream",
        headers={"Content-Disposition": f"attachment; filename={file_id}"}
    )

# Good - Stream database results
@router.get("/export/users")
async def export_users(db: AsyncSession = Depends(get_db)):
    async def generate():
        yield "id,email,username\n"  # CSV header

        result = await db.stream(select(User))
        async for row in result:
            user = row[0]
            yield f"{user.id},{user.email},{user.username}\n"

    return StreamingResponse(
        generate(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=users.csv"}
    )
```

### Pattern 5: Async Database Queries

```python
# Bad - Synchronous query pattern
def get_users_sync(db):
    return db.query(User).filter(User.is_active == True).all()

# Good - Async query pattern
async def get_users_async(db: AsyncSession):
    result = await db.execute(
        select(User).where(User.is_active == True)
    )
    return result.scalars().all()

# Good - Efficient pagination
async def get_users_paginated(
    db: AsyncSession,
    skip: int = 0,
    limit: int = 20
):
    result = await db.execute(
        select(User)
        .where(User.is_active == True)
        .offset(skip)
        .limit(limit)
        .order_by(User.created_at.desc())
    )
    return result.scalars().all()

# Good - Avoid N+1 with eager loading
from sqlalchemy.orm import selectinload

async def get_users_with_orders(db: AsyncSession):
    result = await db.execute(
        select(User)
        .options(selectinload(User.orders))  # Eager load orders
        .where(User.is_active == True)
    )
    return result.scalars().all()
```

### Pattern 6: Background Task Optimization

```python
# Bad - Blocking operation in request
@router.post("/users")
async def create_user(user_in: UserCreate, db: AsyncSession = Depends(get_db)):
    user = await user_crud.create_user(db, user_in)
    await send_welcome_email(user.email)  # Blocks response!
    await notify_admins(user)             # More blocking!
    return user

# Good - Non-blocking background tasks
from fastapi import BackgroundTasks

@router.post("/users")
async def create_user(
    user_in: UserCreate,
    background_tasks: BackgroundTasks,
    db: AsyncSession = Depends(get_db)
):
    user = await user_crud.create_user(db, user_in)

    # Queue non-critical tasks
    background_tasks.add_task(send_welcome_email, user.email)
    background_tasks.add_task(notify_admins, user)

    return user  # Return immediately!

# Good - For heavy tasks, use task queue (Celery/ARQ)
from arq import create_pool

@router.post("/reports/generate")
async def generate_report(report_in: ReportCreate):
    redis = await create_pool(RedisSettings())
    job = await redis.enqueue_job('generate_report', report_in.dict())
    return {"job_id": job.job_id, "status": "queued"}
```

---

## 7. Security Standards

### 7.1 OWASP Top 10 2025 Mapping

| OWASP ID | Category | FastAPI Mitigation |
|----------|----------|-------------------|
| A01:2025 | Broken Access Control | `Depends(get_current_user)` on all protected routes |
| A02:2025 | Security Misconfiguration | Disable docs in prod, use Pydantic Settings |
| A03:2025 | Supply Chain | Pin dependencies in requirements.txt |
| A04:2025 | Insecure Design | Pydantic validation on all inputs |
| A05:2025 | Identification & Auth | JWT with bcrypt, OAuth2PasswordBearer |
| A06:2025 | Vulnerable Components | Run `pip-audit` and `safety check` |
| A07:2025 | Cryptographic Failures | HTTPS only, bcrypt for passwords |
| A08:2025 | Injection | SQLAlchemy ORM, parameterized queries |
| A09:2025 | Logging Failures | Structured logging, exclude secrets |
| A10:2025 | Exception Handling | Custom handlers, hide stack traces |

### 5.2 Input Validation & Injection Prevention

```python
# ✅ PREVENT SQL INJECTION
from pydantic import BaseModel, field_validator

class SearchQuery(BaseModel):
    query: str = Field(..., min_length=1, max_length=100)

    @field_validator('query')
    @classmethod
    def sanitize(cls, v: str) -> str:
        # Block SQL injection patterns
        forbidden = ['--', ';', '/*', 'xp_', 'union', 'select', 'drop']
        if any(p in v.lower() for p in forbidden):
            raise ValueError('Query contains forbidden patterns')
        return v.strip()

# ✅ ALWAYS use ORM (parameterized queries)
result = await db.execute(select(User).where(User.email == email))

# ❌ NEVER string concatenation
# query = f"SELECT * FROM users WHERE email = '{email}'"  # VULNERABLE!
```

### 5.3 CORS Security

```python
# ❌ NEVER use wildcard in production
app.add_middleware(CORSMiddleware, allow_origins=["*"])  # DANGEROUS!

# ✅ Whitelist specific origins
app.add_middleware(CORSMiddleware, allow_origins=[
    "https://yourdomain.com",
    "https://app.yourdomain.com"
])
```

### 5.4 Secrets Management

```python
# .env file (add to .gitignore!)
SECRET_KEY=your-32-char-secret-key-here
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db

# ❌ NEVER hardcode secrets
SECRET_KEY = "my-secret"  # DON'T!

# ✅ Use environment variables
SECRET_KEY = settings.SECRET_KEY

# ❌ NEVER log sensitive data
logger.info(f"Password: {password}")  # DON'T!

# ✅ Sanitize logs
logger.info(f"User {user.email} logged in")
```

### 5.5 Critical Security Rules

**ALWAYS:**
- Use bcrypt for password hashing (cost factor >= 12)
- Implement rate limiting on authentication endpoints
- Validate ALL inputs with Pydantic models
- Use HTTPS in production
- Set short token expiration (15-30 min for access tokens)
- Separate request and response models
- Use parameterized queries (ORM)

**NEVER:**
- Expose password hashes in responses
- Use `allow_origins=["*"]` with credentials
- Disable HTTPS in production
- Trust user input without valid...

© martinholovsky · Unlicense · martinholovsky/claude-skills-generator

Similar skills

All skills for Backend and APIs →

fastapi-expert by other authors comes first.

fastapi-expert https://github.com/Jeffallan fastapi-expert guides async FastAPI development with Pydantic V2, from REST routes and authentication to database operations and tests. CX Codex +1 6,600installs fastapi-expert personamanagmentlayer fastapi-expert — a skill for building FastAPI APIs: Pydantic models, JWT auth, SQLAlchemy integration and background tasks, all with working code patterns. CX Codex +1 218installs fastapi-patterns affaan-m fastapi-patterns provides production patterns for FastAPI, including Pydantic v2 schemas, async dependencies, and service layers. Useful when writing or reviewing API architectures. CX Codex +1 6,700installs FastAPI Service taste f FastAPI Service taste — a prompt for ChatGPT and Claude.ai that enforces backend engineering standards for FastAPI. Sets architectural conventions before generating API code. GP ChatGPT ★ 178,201repo stars fastapi PatrickJS A Cursor rule for FastAPI work in Python. It guides project structure, API design, models, security, database code, testing, and deployment. CX Codex +1 ★ 41,178repo stars api-scaffolding-fastapi-pro Seth Hobson api-scaffolding-fastapi-pro is a Claude Code subagent for building async FastAPI services. It activates for FastAPI development, async performance work, and API architecture tasks. CX Codex ★ 42,780repo stars fastapi-python Mindrally fastapi-python — a skill for Claude Code, Codex, Cursor and other platforms: FastAPI expert with async Python patterns. Activates when building REST APIs, validating with Pydantic or optimizing performance. CX Codex +1 14,100installs fastapi-development aj-geddes fastapi-development — a skill that steers your AI agent toward idiomatic FastAPI code: async routes, Pydantic validation, JWT auth and automatic OpenAPI docs. CX Codex +1 627installs

From the same set50

The whole set →
surrealdb-expert surrealdb-expert guides SurrealDB schema modeling, graph relationships, SurrealQL syntax, and row-level security using test-driven development. CX Codex +1 276installs websocket Walks an agent through locking down a WebSocket endpoint: origin allowlist, token before the handshake, permission checks per message. Useful when sockets are already live or still on the drawing board. CX Codex +1 272installs graph-database-expert graph-database-expert guides graph schema design, relationship modeling, and traversal query optimization with a focus on SurrealDB and Cypher. CX Codex +1 271installs rust rust is a Claude Code skill for writing Rust backends for Tauri desktop apps with attention to memory safety and performance. It covers systems programming tasks, including async code and Tauri commands. CX Codex +1 268installs fastapi fastapi is a Claude Code skill for building FastAPI REST APIs and WebSocket services with security checks. It activates on tasks involving these services and their async patterns. CX Codex +1 265installs async-programming async-programming is a Claude Code skill for writing asynchronous Python and Rust code, with guidance on race conditions and resource safety. It applies to asyncio and Tokio work. CX Codex +1 259installs api-expert api-expert enforces OpenAPI 3.1 and OWASP security standards for REST, GraphQL, and gRPC APIs. Useful when building endpoints via TDD with pytest and httpx. CX Codex +1 258installs threejs-tresjs The threejs-tresjs skill for Claude Code guides creation of 3D HUD interfaces with Three.js, TresJS, and Vue 3. It covers metric panels, status indicators, and particle effects. CX Codex +1 255installs

Project sponsors

Companies that keep this analytics open