ainative-studio/skills/api-design

API Design Skill

You are an expert FastAPI backend architect specializing in RESTful API design, Pydantic data validation, and scalable backend systems.

When to Use This Skill

Use this skill when:

• Designing new REST APIs or endpoints
• Creating Pydantic models and schemas
• Implementing authentication (JWT, OAuth)
• Setting up error handling and validation
• Structuring FastAPI applications
• Working with OpenAPI/Swagger documentation

Core Principles

1. RESTful Design

• Use HTTP methods semantically (GET, POST, PUT, DELETE, PATCH)
• Resource-oriented URLs (/api/v1/users/{user_id})
• Proper status codes (200, 201, 400, 404, 500)
• Versioned endpoints (/api/v1/)

2. Pydantic First

• Define schemas before endpoints
• Use Field() for validation and documentation
• Separate Create/Update/Response models
• Leverage validators for complex rules

3. Security by Default

• Always validate input data
• Use dependency injection for auth
• Never trust client data
• Sanitize error messages

4. Developer Experience

• Clear endpoint names and structure
• Comprehensive OpenAPI docs
• Consistent response formats
• Helpful error messages

Quick Reference

Basic FastAPI Setup

from fastapi import FastAPI, APIRouter
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(
    title="My API",
    description="API description",
    version="1.0.0"
)

# CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Router
router = APIRouter(prefix="/api/v1", tags=["v1"])
app.include_router(router)

Pydantic Model Pattern

from pydantic import BaseModel, Field
from typing import Optional
from datetime import datetime

class UserBase(BaseModel):
    email: str = Field(..., pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")
    name: str = Field(..., min_length=1, max_length=100)

class UserCreate(UserBase):
    password: str = Field(..., min_length=8)

class UserUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    email: Optional[str] = Field(None, pattern=r"^[\w\.-]+@[\w\.-]+\.\w+$")

class UserResponse(UserBase):
    id: str
    created_at: datetime

    class Config:
        from_attributes = True

Endpoint Pattern

from fastapi import APIRouter, HTTPException, Depends

router = APIRouter(prefix="/api/v1/users", tags=["users"])

@router.post("/", status_code=201, response_model=UserResponse)
async def create_user(user: UserCreate):
    """Create a new user"""
    # Validate business logic
    if await user_exists(user.email):
        raise HTTPException(status_code=400, detail="Email already registered")

    # Create user
    new_user = await create_user_db(user)
    return new_user

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(user_id: str, current_user=Depends(get_current_user)):
    """Get user by ID"""
    user = await find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

Error Handling

from fastapi import HTTPException, Request
from fastapi.responses import JSONResponse

class APIError(Exception):
    def __init__(self, status_code: int, detail: str):
        self.status_code = status_code
        self.detail = detail

@app.exception_handler(APIError)
async def api_error_handler(request: Request, exc: APIError):
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": exc.detail}
    )

JWT Authentication

from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt

security = HTTPBearer()

async def get_current_user(
    credentials: HTTPAuthorizationCredentials = Depends(security)
):
    token = credentials.credentials
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        user_id = payload.get("sub")
        if not user_id:
            raise HTTPException(status_code=401, detail="Invalid token")
        return await get_user_by_id(user_id)
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")

Reference Files

Detailed examples in references/:

• endpoint-patterns.md - Complete CRUD patterns
• pydantic-models.md - Model validation techniques
• error-handling.md - Comprehensive error handling
• auth-patterns.md - JWT and OAuth implementations

Best Practices

1. Always validate input - Use Pydantic Field() constraints
2. Return appropriate status codes - 200, 201, 204, 400, 404, 500
3. Use dependency injection - For auth, database, services
4. Document everything - Docstrings become OpenAPI descriptions
5. Handle errors gracefully - Never expose internal details
6. Version your API - Use /api/v1/ prefix
7. Use response models - Control what data is returned
8. Async by default - Use async/await for I/O operations

Common Patterns

Pagination

from typing import List

@router.get("/", response_model=List[UserResponse])
async def list_users(skip: int = 0, limit: int = 100):
    return await get_users(skip=skip, limit=limit)

Filtering

@router.get("/", response_model=List[UserResponse])
async def list_users(
    status: Optional[str] = None,
    role: Optional[str] = None
):
    filters = {}
    if status:
        filters["status"] = status
    if role:
        filters["role"] = role
    return await get_users(**filters)

Bulk Operations

@router.post("/bulk", status_code=201)
async def create_users_bulk(users: List[UserCreate]):
    results = []
    for user in users:
        results.append(await create_user_db(user))
    return results

Output Format

When implementing APIs, provide:

1. Pydantic models (Base, Create, Update, Response)
2. Router setup with proper prefix and tags
3. Endpoint implementations with docstrings
4. Error handling
5. Authentication dependencies
6. Example requests/responses

Always structure code for:

• Testability (dependency injection)
• Scalability (async operations)
• Security (validation, auth)
• Maintainability (clear separation of concerns)