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

Category Rules Impact When to Use

API Framework 3 HIGH REST conventions, resource modeling, OpenAPI specifications

Versioning 3 HIGH URL path versioning, header versioning, deprecation/sunset policies

Error Handling 3 HIGH RFC 9457 Problem Details, validation errors, error type registries

GraphQL 2 HIGH Strawberry code-first, DataLoader, permissions, subscriptions

gRPC 2 HIGH Protobuf services, streaming, interceptors, retry

Streaming 2 HIGH SSE endpoints, WebSocket bidirectional, async generators

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

Total: 17 rules across 7 categories

API Framework

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

Rule File Key Pattern

REST Conventions rules/framework-rest-conventions.md

Plural nouns, HTTP methods, status codes, pagination

Resource Modeling rules/framework-resource-modeling.md

Hierarchical URLs, filtering, sorting, field selection

OpenAPI rules/framework-openapi.md

OpenAPI 3.1 specs, documentation, schema definitions

Versioning

Strategies for API evolution without breaking clients.

Rule File Key Pattern

URL Path rules/versioning-url-path.md

/api/v1/ prefix routing, version-specific schemas

Header rules/versioning-header.md

X-API-Version header, content negotiation

Deprecation rules/versioning-deprecation.md

Sunset headers, lifecycle management, breaking change policy

Error Handling

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

Rule File Key Pattern

Problem Details rules/errors-problem-details.md

RFC 9457 schema, application/problem+json , exception classes

Validation rules/errors-validation.md

Field-level errors, Pydantic integration, 422 responses

Error Catalog rules/errors-error-catalog.md

Problem type registry, error type URIs, client handling

GraphQL

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

Rule File Key Pattern

Schema Design rules/graphql-strawberry.md

Type-safe schema, DataLoader, union errors, Private fields

Patterns & Auth rules/graphql-schema.md

Permission classes, FastAPI integration, subscriptions

gRPC

High-performance gRPC for internal microservice communication.

Rule File Key Pattern

Service Definition rules/grpc-service.md

Protobuf, async server, client timeout, code generation

Streaming & Interceptors rules/grpc-streaming.md

Server/bidirectional streaming, auth, retry backoff

Streaming

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

Rule File Key Pattern

SSE rules/streaming-sse.md

SSE endpoints, LLM streaming, reconnection, keepalive

WebSocket rules/streaming-websocket.md

Bidirectional, heartbeat, aclosing(), backpressure

Integrations

Messaging platform integrations and headless CMS patterns.

Rule File Key Pattern

Messaging Platforms rules/messaging-integrations.md

WhatsApp WAHA, Telegram Bot API, webhook security

Payload CMS rules/payload-cms.md

Payload 3.0 collections, access control, CMS selection

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

Decision Recommendation

Versioning strategy URL path (/api/v1/ ) for public APIs

Resource naming Plural nouns, kebab-case

Pagination Cursor-based for large datasets

Error format RFC 9457 Problem Details with application/problem+json

Error type URI Your API domain + /problems/ prefix

Support window Current + 1 previous version

Deprecation notice 3 months minimum before sunset

Sunset period 6 months after deprecation

GraphQL schema Code-first with Strawberry types

N+1 prevention DataLoader for all nested resolvers

GraphQL auth Permission classes (context-based)

gRPC proto One service per file, shared common.proto

gRPC streaming Server stream for lists, bidirectional for real-time

SSE keepalive Every 30 seconds

WebSocket heartbeat ping-pong every 30 seconds

Async generator cleanup aclosing() for all external resources

Common Mistakes

• Verbs in URLs (POST /createUser instead of POST /users )

• Inconsistent error formats across endpoints

• Breaking contracts without version bump

• Plain text error responses instead of Problem Details

• Sunsetting versions without deprecation headers

• Exposing internal details (stack traces, DB errors) in errors

• Missing Content-Type: application/problem+json on error responses

• Supporting too many concurrent API versions (max 2-3)

• 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?

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