API Design

API Design

Comprehensive API design patterns covering REST/GraphQL framework design, versioning strategies, and RFC 9457 error handling. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

| Integrations | 2 | HIGH | Messaging platforms (WhatsApp, Telegram), Payload CMS patterns |

Total: 18 rules across 7 categories

API Framework

REST and GraphQL API design conventions for consistent, developer-friendly APIs.

Versioning

Strategies for API evolution without breaking clients.

Error Handling

RFC 9457 Problem Details for machine-readable, standardized error responses.

GraphQL

Strawberry GraphQL code-first schema with type-safe resolvers and FastAPI integration.

gRPC

High-performance gRPC for internal microservice communication.

Streaming

Real-time data streaming with SSE, WebSockets, and proper cleanup.

Integrations

Messaging platform integrations and headless CMS patterns.

Quick Start Example

# REST endpoint with versioning and RFC 9457 errors
from fastapi import APIRouter, Depends, Request
from fastapi.responses import JSONResponse

router = APIRouter()

@router.get("/api/v1/users/{user_id}")
async def get_user(user_id: str, service: UserService = Depends()):
    user = await service.get_user(user_id)
    if not user:
        raise NotFoundProblem(
            resource="User",
            resource_id=user_id,
        )
    return UserResponseV1(id=user.id, name=user.full_name)

Key Decisions

Common Mistakes

1. Verbs in URLs (POST /createUser instead of POST /users)
2. Inconsistent error formats across endpoints
3. Breaking contracts without version bump
4. Plain text error responses instead of Problem Details
5. Sunsetting versions without deprecation headers
6. Exposing internal details (stack traces, DB errors) in errors
7. Missing Content-Type: application/problem+json on error responses
8. Supporting too many concurrent API versions (max 2-3)
9. Caching without considering version isolation

Evaluations

See test-cases.json for 9 test cases across all categories.

Related Skills

• fastapi-advanced - FastAPI-specific implementation patterns
• rate-limiting - Advanced rate limiting implementations and algorithms
• observability-monitoring - Version usage metrics and error tracking
• input-validation - Validation patterns beyond API error handling
• streaming-api-patterns - SSE and WebSocket patterns for real-time APIs

Capability Details

rest-design

Keywords: rest, restful, http, endpoint, route, path, resource, CRUD Solves:

• How do I design RESTful APIs?
• REST endpoint patterns and conventions
• HTTP methods and status codes

graphql-design

Keywords: graphql, schema, query, mutation, connection, relay Solves:

• How do I design GraphQL APIs?
• Schema design best practices
• Connection pattern for pagination

endpoint-design

Keywords: endpoint, route, path, resource, CRUD, openapi Solves:

• How do I structure API endpoints?
• What's the best URL pattern for this resource?
• RESTful endpoint naming conventions

url-versioning

Keywords: url version, path version, /v1/, /v2/ Solves:

• How to version REST APIs?
• URL-based API versioning

header-versioning

Keywords: header version, X-API-Version, content negotiation Solves:

• Clean URL versioning
• Header-based API version

deprecation

Keywords: deprecation, sunset, version lifecycle, backward compatible Solves:

• How to deprecate API versions?
• Version sunset policy
• Breaking vs non-breaking changes

problem-details

Keywords: problem details, RFC 9457, RFC 7807, structured error, application/problem+json Solves:

• How to standardize API error responses?
• What format for API errors?

agent-facing-errors

Keywords: agent error, AI agent, retryable, retry_after, error_category, content negotiation, accept header, token efficient, machine readable Solves:

• How to design error responses for AI agent consumers?
• How to reduce token cost of error responses?
• How to enable deterministic agent error handling?
• Content negotiation for agents vs browsers vs LLMs

validation-errors

Keywords: validation, field error, 422, unprocessable, pydantic Solves:

• How to handle validation errors in APIs?
• Field-level error responses

error-registry

Keywords: error registry, problem types, error catalog, error codes Solves:

• How to document all API errors?
• Error type management

Converted and distributed by TomeVault — claim your Tome and manage your conversions.