API Design & Contracts

When Clients Started Breaking

Three months into production, I needed to add a field to the order response. Simple change, right?

# Before
class OrderResponse(BaseModel):
    id: int
    total: float
    status: str

# After - Added items field
class OrderResponse(BaseModel):
    id: int
    total: float
    status: str
    items: List[OrderItem]  # New field

I deployed. Within minutes, clients started failing. Why? Some clients were using strict schema validation and rejected responses with unexpected fields. Others expected items to always be present and crashed when calling old endpoints.

That day I learned: APIs are contracts. Breaking them costs money, trust, and sleep.

REST Principles with FastAPI

Here's how I design APIs for the Restaurant Service:

Resource-Oriented URLs

# restaurant/router.py
from fastapi import APIRouter, Depends, HTTPException, Query
from typing import List, Optional

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

# Collection resource
@router.get("/menus")
async def list_menus(
    tenant_id: str = Depends(get_tenant_id),
    skip: int = Query(0, ge=0),
    limit: int = Query(100, ge=1, le=1000),
    category: Optional[str] = None
):
    """List all menus for tenant"""
    pass

# Individual resource
@router.get("/menus/{menu_id}")
async def get_menu(
    menu_id: int,
    tenant_id: str = Depends(get_tenant_id)
):
    """Get specific menu"""
    pass

# Create resource
@router.post("/menus", status_code=201)
async def create_menu(
    menu: MenuCreate,
    tenant_id: str = Depends(get_tenant_id)
):
    """Create a new menu"""
    pass

# Update resource (full replacement)
@router.put("/menus/{menu_id}")
async def update_menu(
    menu_id: int,
    menu: MenuUpdate,
    tenant_id: str = Depends(get_tenant_id)
):
    """Update entire menu"""
    pass

# Partial update
@router.patch("/menus/{menu_id}")
async def patch_menu(
    menu_id: int,
    updates: MenuPatch,
    tenant_id: str = Depends(get_tenant_id)
):
    """Partially update menu"""
    pass

# Delete resource
@router.delete("/menus/{menu_id}", status_code=204)
async def delete_menu(
    menu_id: int,
    tenant_id: str = Depends(get_tenant_id)
):
    """Delete menu"""
    pass

# Sub-resources
@router.get("/menus/{menu_id}/items")
async def get_menu_items(
    menu_id: int,
    tenant_id: str = Depends(get_tenant_id)
):
    """Get all items in a menu"""
    pass

# Actions on resources
@router.post("/menus/{menu_id}/publish")
async def publish_menu(
    menu_id: int,
    tenant_id: str = Depends(get_tenant_id)
):
    """Publish menu (make it active)"""
    pass

HTTP Status Codes (Use Them Correctly!)

from fastapi import status

# Success responses
@router.post("/menus", status_code=status.HTTP_201_CREATED)  # Created
@router.delete("/menus/{menu_id}", status_code=status.HTTP_204_NO_CONTENT)  # Deleted
@router.get("/menus")  # 200 OK (default)

# Error handling
@router.get("/menus/{menu_id}")
async def get_menu(menu_id: int, tenant_id: str = Depends(get_tenant_id)):
    menu = service.get_menu(menu_id, tenant_id)
    
    if not menu:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Menu {menu_id} not found"
        )
    
    return menu

@router.post("/menus")
async def create_menu(menu: MenuCreate, tenant_id: str = Depends(get_tenant_id)):
    try:
        return service.create_menu(menu, tenant_id)
    except DuplicateMenuError:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Menu with this name already exists"
        )
    except ValidationError as e:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=str(e)
        )

@router.post("/menus/{menu_id}/publish")
async def publish_menu(menu_id: int, user = Depends(get_current_user)):
    if not user.can_publish_menus():
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Insufficient permissions to publish menus"
        )
    
    return service.publish_menu(menu_id, user.tenant_id)

Request/Response Models with Pydantic

Pydantic models are your contract. Make them explicit and strict:

# restaurant/schemas.py
from pydantic import BaseModel, Field, validator
from typing import List, Optional
from datetime import datetime
from enum import Enum

class MenuCategory(str, Enum):
    APPETIZER = "appetizer"
    MAIN_COURSE = "main_course"
    DESSERT = "dessert"
    BEVERAGE = "beverage"

class MenuItemBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=200)
    description: Optional[str] = Field(None, max_length=1000)
    price: float = Field(..., gt=0, description="Price in USD")
    category: MenuCategory
    is_available: bool = True

class MenuItemCreate(MenuItemBase):
    """Request model for creating menu item"""
    
    @validator('price')
    def price_must_have_two_decimals(cls, v):
        if round(v, 2) != v:
            raise ValueError('Price must have at most 2 decimal places')
        return v
    
    @validator('name')
    def name_must_not_be_empty(cls, v):
        if not v.strip():
            raise ValueError('Name cannot be empty or whitespace')
        return v.strip()

class MenuItemResponse(MenuItemBase):
    """Response model for menu item"""
    id: int
    menu_id: int
    created_at: datetime
    updated_at: Optional[datetime]
    
    class Config:
        from_attributes = True  # For SQLAlchemy models

class MenuItemUpdate(BaseModel):
    """Request model for updating menu item (all fields optional)"""
    name: Optional[str] = Field(None, min_length=1, max_length=200)
    description: Optional[str] = Field(None, max_length=1000)
    price: Optional[float] = Field(None, gt=0)
    category: Optional[MenuCategory]
    is_available: Optional[bool]

class MenuBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=200)
    description: Optional[str] = None
    is_active: bool = False

class MenuCreate(MenuBase):
    """Request model for creating menu"""
    items: List[MenuItemCreate] = Field(default_factory=list)

class MenuResponse(MenuBase):
    """Response model for menu"""
    id: int
    tenant_id: str
    item_count: int  # Computed field
    created_at: datetime
    updated_at: Optional[datetime]
    
    class Config:
        from_attributes = True

class MenuDetailResponse(MenuResponse):
    """Detailed response including items"""
    items: List[MenuItemResponse]

class MenuListResponse(BaseModel):
    """Paginated list response"""
    items: List[MenuResponse]
    total: int
    skip: int
    limit: int
    has_more: bool
    
    @classmethod
    def from_query(cls, items: List, total: int, skip: int, limit: int):
        return cls(
            items=items,
            total=total,
            skip=skip,
            limit=limit,
            has_more=(skip + len(items)) < total
        )

class ErrorResponse(BaseModel):
    """Standard error response"""
    error: str
    detail: Optional[str] = None
    timestamp: datetime = Field(default_factory=datetime.utcnow)

# Use in endpoints
@router.post("/menus", response_model=MenuResponse)
async def create_menu(menu: MenuCreate, ...):
    pass

@router.get("/menus", response_model=MenuListResponse)
async def list_menus(...):
    pass

@router.get("/menus/{menu_id}", response_model=MenuDetailResponse)
async def get_menu(...):
    pass

OpenAPI Automatic Generation

FastAPI generates OpenAPI docs automatically. Make them useful:

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI(
    title="POS System - Restaurant Service",
    description="Manage restaurant menus, tables, and dining operations",
    version="1.0.0",
    contact={
        "name": "POS System Team",
        "email": "[email protected]"
    },
    license_info={
        "name": "MIT"
    }
)

# Customize endpoint documentation
@router.post(
    "/menus",
    response_model=MenuResponse,
    status_code=201,
    summary="Create a new menu",
    description="""
    Create a new restaurant menu.
    
    ## Requirements
    - User must have MANAGER or ADMIN role
    - Menu name must be unique within tenant
    
    ## Example Request
    ```json
    {
        "name": "Dinner Menu",
        "description": "Evening dining options",
        "items": [
            {
                "name": "Grilled Salmon",
                "description": "Fresh Atlantic salmon",
                "price": 24.99,
                "category": "main_course"
            }
        ]
    }
    ```
    """,
    responses={
        201: {"description": "Menu created successfully"},
        409: {"description": "Menu name already exists", "model": ErrorResponse},
        422: {"description": "Validation error", "model": ErrorResponse}
    }
)
async def create_menu(menu: MenuCreate, ...):
    pass

# Custom OpenAPI schema
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    
    openapi_schema = get_openapi(
        title=app.title,
        version=app.version,
        description=app.description,
        routes=app.routes,
    )
    
    # Add custom sections
    openapi_schema["info"]["x-logo"] = {
        "url": "https://pos-system.com/logo.png"
    }
    
    # Add security schemes
    openapi_schema["components"]["securitySchemes"] = {
        "BearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT"
        },
        "TenantHeader": {
            "type": "apiKey",
            "in": "header",
            "name": "x-tenant-id"
        }
    }
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

API Versioning Strategies

I learned about versioning the hard way. Here are three approaches:

Strategy 1: URL Versioning (What I Use)

# Explicit, visible versioning in URL
from fastapi import FastAPI

app = FastAPI()

# Version 1
v1_router = APIRouter(prefix="/api/v1")

@v1_router.get("/menus")
async def list_menus_v1():
    return {"version": "v1", "menus": [...]}

# Version 2 with breaking changes
v2_router = APIRouter(prefix="/api/v2")

@v2_router.get("/menus")
async def list_menus_v2():
    # New response format
    return {
        "version": "v2",
        "data": {"menus": [...]},
        "meta": {"total": 10}
    }

app.include_router(v1_router)
app.include_router(v2_router)

# Pros: Clear, easy to route, easy to deprecate
# Cons: URL changes when version changes

Strategy 2: Header Versioning

from fastapi import Header, HTTPException

@app.get("/api/menus")
async def list_menus(api_version: str = Header("1.0", alias="X-API-Version")):
    if api_version == "1.0":
        return list_menus_v1()
    elif api_version == "2.0":
        return list_menus_v2()
    else:
        raise HTTPException(400, f"Unsupported API version: {api_version}")

# Pros: URL stays same, clean URLs
# Cons: Version hidden, harder to test

Strategy 3: Content Negotiation (Media Type)

from fastapi import Request, Response

@app.get("/api/menus")
async def list_menus(request: Request):
    accept_header = request.headers.get("Accept", "")
    
    if "application/vnd.pos.v1+json" in accept_header:
        return Response(
            content=json.dumps(list_menus_v1()),
            media_type="application/vnd.pos.v1+json"
        )
    elif "application/vnd.pos.v2+json" in accept_header:
        return Response(
            content=json.dumps(list_menus_v2()),
            media_type="application/vnd.pos.v2+json"
        )
    else:
        # Default to latest version
        return list_menus_v2()

# Pros: RESTful, follows HTTP standards
# Cons: Complex, rarely used in practice

Breaking vs Non-Breaking Changes

# NON-BREAKING CHANGES (Safe to deploy)

# 1. Adding optional fields to response
class MenuResponse(BaseModel):
    id: int
    name: str
    items: List[MenuItem]
    # Safe to add:
    created_at: Optional[datetime] = None  # Optional, has default

# 2. Adding new endpoints
@router.get("/menus/{menu_id}/analytics")  # New endpoint
async def get_menu_analytics(...):
    pass

# 3. Adding optional query parameters
@router.get("/menus")
async def list_menus(
    skip: int = 0,
    limit: int = 100,
    sort_by: Optional[str] = None  # New, optional parameter
):
    pass

# 4. Deprecating (but not removing) fields
class MenuResponse(BaseModel):
    id: int
    name: str
    total_price: float  # Deprecated, kept for compatibility
    calculated_total: float = Field(alias="total_price")  # New field


# BREAKING CHANGES (Require new API version)

# 1. Removing fields from response
class MenuResponseV2(BaseModel):
    id: int
    name: str
    # BREAKING: Removed 'description' field

# 2. Changing field types
class MenuResponseV2(BaseModel):
    id: str  # BREAKING: Changed from int to str
    price: int  # BREAKING: Changed from float to int

# 3. Making optional fields required
class MenuCreateV2(BaseModel):
    name: str
    description: str  # BREAKING: Was optional, now required

# 4. Changing URL structure
# v1: GET /api/v1/menus/{menu_id}
# v2: GET /api/v2/restaurants/{restaurant_id}/menus/{menu_id}  # BREAKING

# 5. Changing response structure
# v1: {id: 1, name: "Menu"}
# v2: {data: {id: 1, name: "Menu"}}  # BREAKING: Wrapped in 'data'

Managing API Evolution

Here's how I manage multiple versions in production:

# restaurant/versions/v1.py
from fastapi import APIRouter, Depends
from restaurant.schemas.v1 import MenuResponse as MenuResponseV1

router_v1 = APIRouter(prefix="/api/v1/restaurant")

@router_v1.get("/menus/{menu_id}", response_model=MenuResponseV1)
async def get_menu_v1(menu_id: int, tenant_id: str = Depends(get_tenant_id)):
    menu = service.get_menu(menu_id, tenant_id)
    # Convert internal model to v1 response format
    return MenuResponseV1(
        id=menu.id,
        name=menu.name,
        description=menu.description,
        total_items=len(menu.items)
    )

# restaurant/versions/v2.py
from fastapi import APIRouter, Depends
from restaurant.schemas.v2 import MenuDetailResponse as MenuResponseV2

router_v2 = APIRouter(prefix="/api/v2/restaurant")

@router_v2.get("/menus/{menu_id}", response_model=MenuResponseV2)
async def get_menu_v2(menu_id: int, tenant_id: str = Depends(get_tenant_id)):
    menu = service.get_menu(menu_id, tenant_id)
    # Convert to v2 format (includes more details)
    return MenuResponseV2(
        id=menu.id,
        name=menu.name,
        description=menu.description,
        items=[MenuItemResponse(**item.__dict__) for item in menu.items],
        metadata={
            "created_at": menu.created_at,
            "updated_at": menu.updated_at,
            "is_active": menu.is_active
        }
    )

# main.py
app.include_router(router_v1, tags=["Restaurant v1"])
app.include_router(router_v2, tags=["Restaurant v2"])

# Deprecation warnings
@router_v1.get("/menus/{menu_id}")
async def get_menu_v1(...):
    # Add header to warn clients
    response.headers["X-API-Deprecation"] = "This endpoint is deprecated. Use /api/v2/restaurant/menus"
    response.headers["X-API-Sunset"] = "2024-12-31"  # When it will be removed
    return ...

Backward Compatibility Techniques

# Technique 1: Response adapters
class ResponseAdapter:
    @staticmethod
    def to_v1(menu) -> MenuResponseV1:
        return MenuResponseV1(
            id=menu.id,
            name=menu.name,
            total_items=len(menu.items)
        )
    
    @staticmethod
    def to_v2(menu) -> MenuResponseV2:
        return MenuResponseV2(
            id=menu.id,
            name=menu.name,
            items=menu.items,
            metadata={...}
        )

# Technique 2: Field aliases for renames
class MenuResponseV2(BaseModel):
    menu_id: int = Field(alias="id")  # Renamed from 'id' to 'menu_id'
    
    class Config:
        populate_by_name = True  # Accept both 'id' and 'menu_id'

# Technique 3: Optional wrapper for new required fields
class MenuCreateV2(BaseModel):
    name: str
    category: Optional[str] = "general"  # New required field with default
    
    @validator('category', always=True)
    def set_default_category(cls, v):
        return v or "general"

Key Learnings

1. APIs are contracts—treat breaking changes seriously

   • Version your API from day one

   • Never break existing clients

2. Make invalid states unrepresentable

   • Use Pydantic validation

   • Fail fast with clear errors

3. Documentation is part of the contract

   • OpenAPI docs should be accurate

   • Include examples for every endpoint

4. Prefer additive changes

   • Add new fields as optional

   • Deprecate before removing

5. Version explicitly in URL

   • Clear, visible, easy to test

   • Clients know exactly what they're using

Common Mistakes

1. No versioning from the start

   • Adding versioning later is painful

   • Start with /api/v1 on day one

2. Changing response shapes without versioning

   • Breaks clients silently

   • Always introduce as new version

3. Weak request validation

   • Accepting invalid data causes bugs downstream

   • Validate strictly at API boundary

4. Inconsistent error responses

   • Different endpoints return different error formats

   • Standardize error structure

When to Use These Patterns

URL Versioning:

• Most REST APIs

• Clear deprecation path needed

• Multiple versions in production

Header Versioning:

• Internal APIs

• Need stable URLs

• Complex routing logic

Media Type Versioning:

• Following strict REST

• Content negotiation important

• Rare in practice

Next Steps

Now that you understand API design, the next article explores authentication and authorization architecture—how to secure these APIs and manage user permissions.

Next Article: 06-authentication-authorization-architecture.md

---

Remember: Your API is a product. Breaking it breaks your users' code. Version early, deprecate gracefully, and never surprise your clients.