api-design-patterns

# 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` ## Core Principles ### Universal API Design Standards Apply these principles across all API styles: **1. Consistency Over Cleverness** - Follow established conventions for your API style - Use predictable naming patterns (snake_case or camelCase, pick one) - Maintain consistent error response formats - Version breaking changes, never surprise clients **2. Design for Evolution** - Plan for versioning from day one - Use optional fields with sensible defaults - Deprecate gracefully with sunset dates - Document breaking vs...