api-design

API Design

Build production-ready REST APIs with standardized patterns for routing, pagination, error handling, versioning, and OpenAPI documentation.

When to Use

• Creating new REST API endpoints
• Defining API contracts and response schemas
• Adding pagination, filtering, or sorting to list endpoints
• Implementing standardized error handling
• Setting up API versioning strategy
• Generating OpenAPI/Swagger documentation

Available Operations

1. Create CRUD endpoints with FastAPI
2. Define request/response models with Pydantic
3. Implement standardized error handling
4. Add pagination to list endpoints
5. Configure API versioning
6. Generate and validate OpenAPI documentation

Multi-Step Workflow

Step 1: Define the REST Contract

Map business operations to HTTP methods and paths.

Operation	Method	Path	Status	Body
List	GET	/api/v1/demands	200	Paginated list
Get	GET	/api/v1/demands/{id}	200	Single object
Create	POST	/api/v1/demands	201	Created object
Update	PUT	/api/v1/demands/{id}	200	Updated object
Patch	PATCH	/api/v1/demands/{id}	200	Updated object
Delete	DELETE	/api/v1/demands/{id}	204	Empty

Step 2: Create the Controller with FastAPI

from fastapi import APIRouter, Depends, HTTPException, Query

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

@router.get("/", response_model=PaginatedResponse[DemandResponse])
async def list_demands(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
    status: str | None = None,
    use_case: ListDemands = Depends()
):
    result = use_case.execute(page=page, size=size, status=status)
    return PaginatedResponse(
        items=result.items,
        total=result.total,
        page=page,
        size=size
    )

@router.post("/", response_model=DemandResponse, status_code=201)
async def create_demand(
    body: CreateDemandRequest,
    use_case: CreateDemand = Depends()
):
    return use_case.execute(body)

@router.get("/{demand_id}", response_model=DemandResponse)
async def get_demand(
    demand_id: str,
    use_case: GetDemand = Depends()
):
    result = use_case.execute(demand_id)
    if not result:
        raise HTTPException(status_code=404, detail="Demand not found")
    return result