fastapi-api-patterns

What this skill does

# fastapi-api-patterns

## Instructions

This skill provides comprehensive REST API design patterns and implementation templates for FastAPI applications. It covers CRUD operations, pagination, filtering, request/response models, error handling, and API organization following modern best practices.

### 1. CRUD Endpoint Patterns

Create, Read, Update, Delete endpoints using FastAPI routers:

```bash
# Use CRUD template to generate complete endpoint set
cp ./skills/fastapi-api-patterns/templates/crud_endpoint.py app/routers/items.py

# Customize for your model
# - Replace Item model with your Pydantic model
# - Update database operations
# - Add authentication dependencies
```

**What This Provides:**
- `POST /items/` - Create new item
- `GET /items/{item_id}` - Read single item by ID
- `GET /items/` - Read multiple items with pagination
- `PUT /items/{item_id}` - Update entire item
- `PATCH /items/{item_id}` - Partial update
- `DELETE /items/{item_id}` - Delete item

**Router Structure:**
```python
from fastapi import APIRouter, HTTPException, Depends, status
from typing import List

router = APIRouter(
    prefix="/items",
    tags=["items"],
    responses={404: {"description": "Not found"}},
)
```

### 2. Pagination and Filtering

Implement pagination with query parameters:

```bash
# Use pagination template
cp ./skills/fastapi-api-patterns/templates/pagination.py app/utils/pagination.py
```

**Pagination Strategies:**

**1. Offset-Based Pagination (Simple):**
```python
@router.get("/items/")
async def list_items(skip: int = 0, limit: int = 10):
    return items[skip : skip + limit]
```

**2. Cursor-Based Pagination (Performance):**
```python
@router.get("/items/")
async def list_items(cursor: str | None = None, limit: int = 10):
    # Use last item ID as cursor for next page
    # Better for large datasets
```

**3. Page-Based Pagination (User-Friendly):**
```python
@router.get("/items/")
async def list_items(page: int = 1, page_size: int = 10):
    skip = (page - 1) * page_size
    return items[skip : skip + page_size]
```

**Filtering Patterns:**
```python
@router.get("/items/")
async def list_items(
    skip: int = 0,
    limit: int = 10,
    category: str | None = None,
    min_price: float | None = None,
    max_price: float | None = None,
    search: str | None = None,
):
    # Apply filters before pagination
    filtered_items = apply_filters(items, category, min_price, max_price, search)
    return filtered_items[skip : skip + limit]
```

**Sorting:**
```python
from enum import Enum

class SortBy(str, Enum):
    name = "name"
    price = "price"
    created_at = "created_at"

@router.get("/items/")
async def list_items(
    sort_by: SortBy = SortBy.created_at,
    order: Literal["asc", "desc"] = "desc",
):
    # Sort before returning
```

### 3. Request and Response Models

Define clear Pydantic models for type safety and validation:

**Base Models:**
```python
from pydantic import BaseModel, Field, validator
from datetime import datetime

class ItemBase(BaseModel):
    """Shared properties"""
    name: str = Field(..., min_length=1, max_length=100)
    description: str | None = Field(None, max_length=500)
    price: float = Field(..., gt=0)
    category: str

class ItemCreate(ItemBase):
    """Properties required for creation"""
    pass

class ItemUpdate(BaseModel):
    """Properties that can be updated"""
    name: str | None = None
    description: str | None = None
    price: float | None = Field(None, gt=0)
    category: str | None = None

class ItemInDB(ItemBase):
    """Properties stored in database"""
    id: int
    created_at: datetime
    updated_at: datetime

class Item(ItemInDB):
    """Properties returned to client"""
    class Config:
        from_attributes = True
```

**Response Models with Metadata:**
```python
from typing import Generic, TypeVar, List
from pydantic import BaseModel

T = TypeVar('T')

class PaginatedResponse(BaseModel, Generic[T]):
    items: List[T]
    total: int
    page: int
    page_size: int
    pages: int

@router.get("/items/", response_model=PaginatedResponse[Item])
async def list_items(page: int = 1, page_size: int = 10):
    total = len(items)
    pages = (total + page_size - 1) // page_size
    skip = (page - 1) * page_size

    return PaginatedResponse(
        items=items[skip : skip + page_size],
        total=total,
        page=page,
        page_size=page_size,
        pages=pages,
    )
```

### 4. Error Handling Strategies

Implement consistent error handling:

```bash
# Use error handling template
cp ./skills/fastapi-api-patterns/templates/error_handling.py app/utils/errors.py
```

**HTTP Exception Patterns:**
```python
from fastapi import HTTPException, status

# 404 Not Found
if item is None:
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail=f"Item with id {item_id} not found"
    )

# 400 Bad Request
if price < 0:
    raise HTTPException(
        status_code=status.HTTP_400_BAD_REQUEST,
        detail="Price must be positive"
    )

# 409 Conflict
if item_exists:
    raise HTTPException(
        status_code=status.HTTP_409_CONFLICT,
        detail="Item with this name already exists"
    )

# 403 Forbidden
if not is_owner:
    raise HTTPException(
        status_code=status.HTTP_403_FORBIDDEN,
        detail="Not authorized to modify this item"
    )
```

**Custom Exception Handlers:**
```python
from fastapi import Request
from fastapi.responses import JSONResponse

class ItemNotFoundError(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFoundError)
async def item_not_found_handler(request: Request, exc: ItemNotFoundError):
    return JSONResponse(
        status_code=404,
        content={
            "error": "not_found",
            "message": f"Item {exc.item_id} not found",
            "item_id": exc.item_id
        }
    )
```

**Validation Error Customization:**
```python
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={
            "error": "validation_error",
            "message": "Invalid request data",
            "details": exc.errors()
        }
    )
```

### 5. Dependency Injection for Common Logic

Use dependencies for authentication, database sessions, and validation:

```python
from fastapi import Depends, Header, HTTPException

# Authentication dependency
async def verify_token(x_token: str = Header(...)):
    if x_token != "secret-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return x_token

# Database session dependency
async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

# Pagination dependency
async def pagination_params(
    skip: int = 0,
    limit: int = 10,
    max_limit: int = 100
):
    if limit > max_limit:
        limit = max_limit
    return {"skip": skip, "limit": limit}

# Use in endpoints
@router.get("/items/")
async def list_items(
    token: str = Depends(verify_token),
    db: Session = Depends(get_db),
    pagination: dict = Depends(pagination_params),
):
    return db.query(Item).offset(pagination["skip"]).limit(pagination["limit"]).all()
```

### 6. API Router Organization

Structure APIs with APIRouter for modularity:

```python
# app/routers/items.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

# app/main.py
from fastapi import FastAPI
from app.routers import items, users

app = FastAPI()

app.include_router(items.router)
app.include_router(users.router, prefix="/api/v1")
```

### 7. OpenAPI Documentation Enhancement

Generate better API documentation:

```bash
# Gene