FastAPI Development Standards

This skill guides development of FastAPI endpoints for the E-Signature Platform API.

Endpoint Implementation Checklist

1. Pydantic Models: Always define request/response schemas in app/schemas/
2. Error Handling: Use error codes from esig-design.md Error Code Catalog
3. Authentication: Use getcurrentuser dependency for protected routes
4. Validation: Implement constraints from esig-design.md (e.g., name 1-255 chars)
5. Idempotency: Create endpoints accept Idempotency-Key header
6. Tests: Write success, validation error, and auth error test cases

Error Response Format

All errors must follow the standard format from esig-design.md:

from fastapi import HTTPException

# Standard error response
raise HTTPException(
    status_code=404,
    detail={
        "error": {
            "code": "ENVELOPE_NOT_FOUND",
            "message": "Envelope does not exist",
            "details": {}
        }
    }
)

Error Code Reference (esig-design.md)

Authentication Patterns

from app.dependencies import get_current_user, get_db
from app.models.user import User
from sqlalchemy.ext.asyncio import AsyncSession

# Protected endpoint (any authenticated user)
@router.get("/envelopes")
async def list_envelopes(
    user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db)
):
    ...

# Optional auth (for public signing endpoints)
@router.get("/signing/{token}")
async def get_signing_session(
    token: str,
    db: AsyncSession = Depends(get_db)
):
    # Validate signing token instead of JWT
    ...

Pagination Pattern

Use cursor-based pagination:

from app.schemas.common import PaginatedResponse

@router.get("/envelopes", response_model=PaginatedResponse[EnvelopeListItem])
async def list_envelopes(
    limit: int = Query(default=20, ge=1, le=100),
    cursor: str | None = Query(default=None),
    status: str | None = Query(default=None),
    user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db)
):
    # Decode cursor, query with limit+1, encode next_cursor
    ...
    return {
        "items": envelopes[:limit],
        "next_cursor": encode_cursor(envelopes[limit].id) if len(envelopes) > limit else None
    }

Idempotency Pattern

from app.utils.idempotency import check_idempotency, store_idempotency

@router.post("/envelopes")
async def create_envelope(
    envelope_data: EnvelopeCreate,
    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
    user: User = Depends(get_current_user),
    db: AsyncSession = Depends(get_db)
):
    # Check for existing response
    if idempotency_key:
        cached = await check_idempotency(db, idempotency_key, user.id)
        if cached:
            return cached

    # Process request
    envelope = await create_envelope_impl(db, user.id, envelope_data)

    # Store for idempotency
    if idempotency_key:
        await store_idempotency(db, idempotency_key, user.id, envelope)

    return envelope

Validation Constraints (from esig-design.md)

After Implementation

Run these commands after creating/modifying endpoints:

# Format code
ruff format backend/

# Type check
uv run mypy app/

# Run tests for the module
uv run pytest tests/test_<module>.py -v

File Organization

app/
├── routers/<resource>.py    # Endpoint definitions
├── schemas/<resource>.py    # Pydantic models
├── models/<resource>.py     # SQLAlchemy models
└── services/<resource>.py   # Business logic (if complex)