API Development Patterns

API Development Patterns

Implements practical patterns for building production-ready APIs that are consistent, resilient, and maintainable. When loaded, this skill makes the model act as a senior API engineer — designing RESTful endpoints, crafting GraphQL schemas, implementing robust error handling, managing API versioning strategies, and enforcing contract-first development workflows with OpenAPI specifications.

TL;DR Checklist

• Design all APIs using an OpenAPI/Swagger spec first, then implement against it
• Follow consistent REST conventions: resource-oriented URLs, proper HTTP methods, status codes
• Implement structured error responses with error codes, messages, and context for debugging
• Version APIs explicitly (URI path versioning preferred) and maintain backward compatibility
• Add pagination, filtering, and sorting to all collection endpoints
• Include rate limiting headers and CORS configuration on all responses

When to Use

Use this skill when:

• Designing a new REST or GraphQL API from scratch
• Refactoring an existing API for better consistency, versioning, or error handling
• Integrating with a third-party API that has inconsistent patterns — need a consistent abstraction layer
• Setting up contract-first development with OpenAPI specs for your team
• Building internal APIs (BFFs, aggregation layers) that front multiple microservices
• Creating public-facing APIs that require versioning, rate limiting, and comprehensive documentation

When NOT to Use

Avoid this skill for:

• Designing low-level service-to-service communication where gRPC or message queues are more appropriate — use grpc-patterns instead
• Implementing API security (authentication, authorization, input validation at trust boundaries) — use api-security-patterns or security-review instead
• GraphQL-specific resolver implementation and data loading — that's a sub-problem covered by graphql-schema-design

Core Workflow

1. Define the OpenAPI Contract First — Before writing any implementation code, create an OpenAPI 3.x specification document that defines all endpoints, request/response schemas, error formats, and authentication requirements:

   • Define paths with resource-oriented naming (plural nouns, /users, /orders/{id}/items)
   • Specify HTTP methods semantically (GET=fetch, POST=create, PUT=replace, PATCH=partial update, DELETE=remove)
   • Document all response codes including error responses with structured schemas
   • Define request body schemas using reusable component definitions Checkpoint: Every endpoint must have at least one success response (2xx), one client error response (4xx), and one server error response (5xx) defined in the spec. If any are missing, the API is incomplete.

2. Implement RESTful Endpoint Patterns — For each endpoint defined in the contract, implement using consistent patterns:

   • Collection endpoints return paginated lists with Link headers for navigation
   • Resource endpoints use UUID or surrogate keys as identifiers (never expose internal database IDs)
   • Create operations use POST and return 201 with a Location header pointing to the created resource
   • Update operations: PUT replaces the entire resource, PATCH modifies specific fields
   • Delete operations return 204 No Content on success Checkpoint: Run all endpoints through an HTTP method stress test — verify that GET is idempotent and safe (read-only), POST is non-idempotent, and PUT is truly replace-all. Any deviation indicates a design flaw.

3. Implement Structured Error Handling — Create a unified error response format used across all endpoints:

   • Include error_code for machine-readable error classification
   • Include message for human-readable explanation
   • Include details array for field-level validation errors
   • Use correct HTTP status codes: 400 (client error), 401 (unauthenticated), 403 (forbidden), 404 (not found), 409 (conflict), 422 (validation), 500 (internal)
   • Never expose stack traces or internal implementation details to clients Checkpoint: Every error path in the codebase must go through the same error handler. Verify by adding a random exception and confirming it produces a properly formatted error response, not a raw stack trace.

4. Design Pagination, Filtering, and Sorting — All collection endpoints must support:

   • Cursor-based pagination (preferred for large datasets) or offset-based (acceptable for small collections)
   • Consistent pagination envelope: { items: [...], next_cursor: "...", has_more: bool }
   • Query parameter filtering with field prefixes: /users?role=admin&status=active
   • Sorting by multiple fields: /orders?sort=-created_at,name (dash prefix = descending) Checkpoint: Verify that pagination works correctly at boundaries — empty result set, exactly one page of results, and the last item of a multi-page result. These are where bugs hide.

5. Implement API Versioning Strategy — Use URI path versioning for public APIs:

   • Base URL pattern: /api/v1/resources, /api/v2/resources
   • Each version must maintain backward compatibility with its previous version
   • Deprecation notices appear in response headers 90 days before end-of-life
   • Internal APIs can use simpler strategies (header-based, semantic versioning) Checkpoint: When adding a new field to a response schema, it MUST be optional for at least one major version cycle before becoming required. This is the golden rule of API evolution.

6. Add Operational Headers and CORS — Every API response must include:

   • X-Request-ID: Unique identifier for request tracing across services
   • X-RateLimit-Limit / X-RateLimit-Remaining: Current rate limit status
   • X-API-Version: Which API version this response conforms to
   • Proper CORS headers when serving cross-origin requests Checkpoint: Verify that every production endpoint includes these headers by checking the actual HTTP responses, not just the code. Headers can be stripped by middleware misconfiguration.

Implementation Patterns

Pattern 1: RESTful Endpoint Implementations

Consistent implementation patterns for CRUD operations on a resource, following REST conventions and OpenAPI-first design.

from __future__ import annotations

from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum
from typing import Any


# ---- Unified Error Response Schema ----

class ErrorCode(str, Enum):
    VALIDATION_ERROR = "validation_error"
    NOT_FOUND = "not_found"
    UNAUTHORIZED = "unauthorized"
    FORBIDDEN = "forbidden"
    CONFLICT = "conflict"
    RATE_LIMITED = "rate_limited"
    INTERNAL_ERROR = "internal_error"


@dataclass
class FieldError:
    field: str
    message: str
    code: str = ""


@dataclass
class ApiError:
    """Standardized API error response used across all endpoints."""
    error_code: ErrorCode
    message: str
    details: list[FieldError] = field(default_factory=list)
    request_id: str = ""

    def to_dict(self, include_request_id: bool = True) -> dict[str, Any]:
        result: dict[str, Any] = {
            "error_code": self.error_code.value,
            "message": self.message,
        }
        if self.details:
            result["details"] = [
                {"field": d.field, "message": d.message} for d in self.details
            ]
        if include_request_id and self.request_id:
            result["request_id"] = self.request_id
        return result


class ApiErrorResponse(Exception):
    """Base exception for API errors that produces structured HTTP responses."""

    def __init__(
        self,
        status_code: int,
        error_code: ErrorCode,
        message: str,
        details: list[FieldError] | None = None,
    ):
        self.status_code = status_code
        self.error_code = error_code
        self.message = message
        self.details = details or []

    def response(self, request_id: str = "") -> ApiError:
        return ApiError(
            error_code=self.error_code,
            message=self.message,
            details=self.details,
            request_id=request_id,
        )


# ---- Pagination Envelope ----

@dataclass
class PaginatedResponse[T]:
    """Consistent pagination envelope for all collection endpoints."""
    items: list[T]
    next_cursor: str | None = None
    has_more: bool = False

    def to_dict(self) -> dict[str, Any]:
        return {
            "items": self.items,
            "next_cursor": self.next_cursor,
            "has_more": self.has_more,
        }


# ---- Example RESTful Resource Handlers ----

class UserService:
    """Example service demonstrating consistent REST endpoint patterns."""

    async def list_users(
        self,
        cursor: str | None = None,
        page_size: int = 20,
        role: str | None = None,
        status: str | None = None,
    ) -> PaginatedResponse[dict]:
        """List users with cursor-based pagination and filtering.

        GET /api/v1/users?cursor=<token>&page_size=20&role=admin&status=active

        Args:
            cursor: Opaque cursor for pagination continuation.
            page_size: Number of results per page (max 100).
            role: Filter by user role.
            status: Filter by account status.

        Returns:
            Paginated list of user objects.
        """
        if page_size < 1 or page_size > 100:
            raise ApiErrorResponse(
                status_code=422,
                error_code=ErrorCode.VALIDATION_ERROR,
                message="page_size must be between 1 and 100",
                details=[FieldError(field="page_size", message="Range: 1-100")],
            )

        # ... actual implementation would query database here ...
        users = []  # Placeholder for actual data fetch
        has_more = len(users) == page_size
        next_cursor = None if not has_more else "eyJpZCI6IDEyM30"  # Opaque cursor token

        return PaginatedResponse(items=users, next_cursor=next_cursor, has_more=has_more)

    async def get_user(self, user_id: str) -> dict:
        """Get a single user by UUID.

        GET /api/v1/users/{user_id}
        """
        # Validate UUID format
        import uuid
        try:
            uuid.UUID(user_id)
        except ValueError:
            raise ApiErrorResponse(
                status_code=422,
                error_code=ErrorCode.VALIDATION_ERROR,
                message="Invalid user ID format. Expected a valid UUID.",
                details=[FieldError(field="user_id", message="Must be a valid UUID")],
            )

        # ... actual implementation would query database ...
        return {"id": user_id, "name": "Example User"}

    async def create_user(self, name: str, email: str, role: str = "member") -> dict:
        """Create a new user. Returns 201 with Location header.

        POST /api/v1/users
        """
        # Validate email format
        if "@" not in email or "." not in email.split("@")[1]:
            raise ApiErrorResponse(
                status_code=422,
                error_code=ErrorCode.VALIDATION_ERROR,
                message="Invalid email format",
                details=[FieldError(field="email", message="Must be a valid email address")],
            )

        # ... actual implementation would insert into database ...
        return {"id": str(uuid.uuid4()), "name": name, "email": email, "role": role}

Pattern 2: Structured Error Handler Middleware

A centralized error handler that ensures every API error follows the unified format, regardless of where it originates in the application.

from __future__ import annotations

import logging
import traceback
from typing import Any

logger = logging.getLogger(__name__)


class ErrorHandlerMiddleware:
    """Centralized middleware that catches all exceptions and converts them
    to standardized API error responses with proper HTTP status codes.

    Usage in FastAPI:
        app.add_middleware(ErrorHandlerMiddleware)
    """

    @staticmethod
    def handle(exception: Exception, request_id: str = "") -> tuple[int, dict[str, Any]]:
        """Convert any exception to a (status_code, body) response tuple.

        Args:
            exception: The caught exception.
            request_id: The request identifier for tracing.

        Returns:
            Tuple of HTTP status code and error response body.
        """
        # Map known exception types to error codes
        if isinstance(exception, ApiErrorResponse):
            err = exception.response(request_id)
            return exception.status_code, err.to_dict()

        # Handle validation errors (e.g., Pydantic)
        from pydantic import ValidationError
        if isinstance(exception, ValidationError):
            details = []
            for error in exception.errors():
                field_name = ".".join(str(loc) for loc in error["loc"])
                details.append(FieldError(
                    field=field_name,
                    message=error["msg"],
                    code=ErrorCode.VALIDATION_ERROR.value,
                ))
            err = ApiError(
                error_code=ErrorCode.VALIDATION_ERROR,
                message="Request validation failed",
                details=details,
                request_id=request_id,
            )
            return 422, err.to_dict()

        # Handle generic exceptions — never expose internals to the client
        logger.exception("Unhandled exception in request handler")
        err = ApiError(
            error_code=ErrorCode.INTERNAL_ERROR,
            message="An unexpected error occurred. Please contact support.",
            request_id=request_id,
        )
        return 500, err.to_dict()


# BAD: Raw exception leaking to client — DO NOT DO THIS
def bad_error_handler(exc):
    """❌ BAD: Returns raw traceback and internal details."""
    return {
        "error": str(exc),
        "traceback": traceback.format_exc(),  # Never expose stack traces!
        "internal_path": exc.__module__ + "." + type(exc).__name__,
    }


# GOOD: Structured error with controlled message
def good_error_handler(exc, request_id=""):
    """✅ GOOD: Catches all exceptions and returns structured API error."""
    status_code, body = ErrorHandlerMiddleware.handle(exc, request_id)
    return {"status": status_code, "body": body}

Pattern 3: OpenAPI Contract Generator

Generates OpenAPI 3.x specifications from code annotations, ensuring the contract stays in sync with implementation.

from __future__ import annotations

import json
from dataclasses import asdict, dataclass, field
from typing import Any


@dataclass
class ApiEndpoint:
    """Represents a single API endpoint for OpenAPI spec generation."""
    path: str
    method: str  # "get", "post", "put", "patch", "delete"
    summary: str
    description: str = ""
    parameters: list[dict[str, Any]] = field(default_factory=list)
    request_body: dict[str, Any] | None = None
    responses: dict[str, dict[str, Any]] = field(default_factory=dict)
    tags: list[str] = field(default_factory=list)


class OpenAPISpecBuilder:
    """Builds and validates OpenAPI 3.x specifications from endpoint definitions.

    Usage:
        builder = OpenAPISpecBuilder(title="My API", version="1.0.0")
        builder.add_endpoint(ApiEndpoint(
            path="/api/v1/users",
            method="get",
            summary="List all users",
            tags=["users"],
            parameters=[...],
            responses={"200": {...}, "422": {...}},
        ))
        spec = builder.build()
    """

    def __init__(self, title: str, version: str = "1.0.0", description: str = ""):
        self.title = title
        self.version = version
        self.description = description
        self.paths: dict[str, dict[str, Any]] = {}
        self.components: dict[str, Any] = {"schemas": {}}

    def add_endpoint(self, endpoint: ApiEndpoint) -> "OpenAPISpecBuilder":
        """Add an endpoint to the specification."""
        method_lower = endpoint.method.lower()

        if endpoint.path not in self.paths:
            self.paths[endpoint.path] = {}

        operation: dict[str, Any] = {
            "summary": endpoint.summary,
            "tags": endpoint.tags,
        }

        if endpoint.description:
            operation["description"] = endpoint.description

        if endpoint.parameters:
            operation["parameters"] = endpoint.parameters

        if endpoint.request_body:
            operation["requestBody"] = {"required": True, "content": endpoint.request_body}

        operation["responses"] = {}
        for code, response in endpoint.responses.items():
            operation["responses"][code] = {
                "description": response.get("description", f"Response code {code}"),
            }
            if "schema" in response:
                operation["responses"][code]["content"] = {
                    "application/json": {"schema": response["schema"]}
                }

        self.paths[endpoint.path][method_lower] = operation
        return self

    def build(self) -> dict[str, Any]:
        """Build the complete OpenAPI 3.x specification dictionary."""
        spec: dict[str, Any] = {
            "openapi": "3.1.0",
            "info": {
                "title": self.title,
                "version": self.version,
                "description": self.description,
            },
            "paths": self.paths,
            "components": self.components,
        }

        # Validate required fields
        if not spec["paths"]:
            raise ValueError("OpenAPI spec must have at least one endpoint")

        return spec

    def to_json(self, indent: int = 2) -> str:
        """Serialize the spec to a formatted JSON string."""
        return json.dumps(self.build(), indent=indent, default=str)


# Example: Building a complete spec for a users API
def build_users_api_spec() -> str:
    """Generate an OpenAPI specification for a sample users API."""
    builder = OpenAPISpecBuilder(
        title="User Management API",
        version="1.0.0",
        description="RESTful user management with pagination and filtering.",
    )

    # List users endpoint
    builder.add_endpoint(ApiEndpoint(
        path="/api/v1/users",
        method="get",
        summary="List all users",
        tags=["users"],
        parameters=[
            {
                "name": "page_size",
                "in": "query",
                "schema": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100},
                "description": "Number of results per page",
            },
            {
                "name": "cursor",
                "in": "query",
                "schema": {"type": "string"},
                "description": "Cursor for pagination continuation",
            },
            {
                "name": "role",
                "in": "query",
                "schema": {"type": "string"},
                "description": "Filter by user role",
            },
        ],
        responses={
            "200": {
                "description": "Successful response with paginated users",
                "schema": {"$ref": "#/components/schemas/PaginatedUsers"},
            },
            "422": {
                "description": "Validation error",
                "schema": {"$ref": "#/components/schemas/ApiError"},
            },
        },
    ))

    # Get user endpoint
    builder.add_endpoint(ApiEndpoint(
        path="/api/v1/users/{user_id}",
        method="get",
        summary="Get a single user",
        tags=["users"],
        parameters=[
            {
                "name": "user_id",
                "in": "path",
                "required": True,
                "schema": {"type": "string", "format": "uuid"},
                "description": "UUID of the user to retrieve",
            },
        ],
        responses={
            "200": {
                "description": "User found",
                "schema": {"$ref": "#/components/schemas/User"},
            },
            "404": {
                "description": "User not found",
                "schema": {"$ref": "#/components/schemas/ApiError"},
            },
        },
    ))

    # Create user endpoint
    builder.add_endpoint(ApiEndpoint(
        path="/api/v1/users",
        method="post",
        summary="Create a new user",
        tags=["users"],
        request_body={
            "application/json": {
                "schema": {"$ref": "#/components/schemas/CreateUserRequest"},
            },
        },
        responses={
            "201": {
                "description": "User created successfully",
                "schema": {"$ref": "#/components/schemas/User"},
            },
            "422": {
                "description": "Validation error",
                "schema": {"$ref": "#/components/schemas/ApiError"},
            },
        },
    ))

    return builder.to_json()

Constraints

MUST DO

• Start every new API with an OpenAPI 3.x specification before writing implementation code
• Use plural noun paths for resources (/users, not /user or /get-user)
• Return structured error responses with error_code, message, and optional details on every endpoint
• Implement cursor-based pagination for all collection endpoints that may return more than 100 items
• Include X-Request-ID in every request/response pair for tracing across services
• Version public APIs using URI path versioning (/api/v1/...) with backward compatibility guarantees
• Add rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining) on all endpoints
• Never expose stack traces, internal paths, or database queries in API error responses

MUST NOT DO

• Use query parameters for resource identification (e.g., /users?id=123 instead of /users/123)
• Return HTTP 200 for all successful responses regardless of operation type (use 201 for create, 204 for delete)
• Mutate the existing error handling across different endpoints — use a single centralized handler
• Expose internal database primary keys in API responses (use UUIDs or opaque identifiers)
• Add required fields to response schemas without a deprecation cycle of at least one major version
• Use DELETE with a request body — DELETE should operate on the URL resource identifier only

Output Template

When designing or reviewing an API, produce:

1. API Specification — Complete OpenAPI 3.x YAML/JSON spec with all endpoints, schemas, and error formats defined
2. RESTful Implementation Examples — Handler code for each endpoint using consistent patterns (pagination, error handling)
3. Error Handling Strategy — The centralized error handler implementation and error code catalog
4. Versioning Plan — Current version state, deprecated endpoints timeline, and migration path to next version
5. Operational Headers Configuration — CORS settings, rate limiting rules, and request tracing setup

Related Skills

Live References

Authoritative documentation for API development practices.

• OpenAPI Specification 3.1 Documentation
• RESTful API Design Guidelines — Microsoft
• RFC 9110 — HTTP Semantics (official REST conventions)
• Paginating APIs — GitHub Developer Guide
• API Versioning Strategies — Martin Kleppmann Blog