API Design Patterns

Design robust, scalable APIs using proven patterns for REST, GraphQL, and gRPC with proper versioning, authentication, and error handling.

Quick Reference

API Style Selection:

• REST: Resource-based CRUD, simple clients, HTTP-native caching
• GraphQL: Client-driven queries, complex data graphs, real-time subscriptions
• gRPC: High-performance RPC, microservices, strong typing, streaming

Critical Patterns:

• Versioning: URI (/v1/users), header (Accept: application/vnd.api+json;version=1), content negotiation
• Pagination: Offset (simple), cursor (stable), keyset (performant)
• Auth: OAuth2 (delegated), JWT (stateless), API keys (service-to-service)
• Rate limiting: Token bucket, fixed window, sliding window
• Idempotency: Idempotency keys, conditional requests, safe retry

See references/ for deep dives: rest-patterns.md, graphql-patterns.md, grpc-patterns.md, versioning-strategies.md, authentication.md