API Design Principles

--- name: api-design-principles description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards. --- # API Design Principles Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time. ## When to Use This Skill - Designing new REST or GraphQL APIs - Refactoring existing APIs for better usability - Establishing API design standards for your team - Reviewing API specifications before implementation - Migrating between API paradigms (REST to GraphQL, etc.) - Creating developer-friendly API documentation - Optimizing APIs for specific use cases (mobile, third-party integrations) ## Core Concepts ### 1. RESTful Design Principles Resource-Oriented Architecture - Resources are nouns (users, orders, products), not verbs - Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE) - URLs represent resource hierarchies - Consistent naming conventions HTTP Methods Semantics: - GET: Retrieve resources (idempotent, safe) - POST: Create new resources - PUT: Replace entire resource (idempotent) - PATCH: Partial resource updates - DELETE: Remove resources (idempotent) ### 2. GraphQL Design Principles Schema-First Development - Types define your domain model - Queries for reading data - Mutations for modifying data - Subscriptions for real-time updates Query Structure: - Clients request exactly what they need - Single endpoint, multiple operations - Strongly typed schema - Introspection built-in ### 3. API Versioning Strategies URL Versioning: `` /api/v1/users /api/v2/users ` **Header Versioning:** ` Accept: application/vnd.api+json; version=1 ` **Query Parameter Versioning:** ` /api/users?version=1 ` ## Detailed patterns and worked examples Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient. ## Best Practices ### REST APIs 1. **Consistent Naming**: Use plural nouns for collections (/users, not /user) 2. **Stateless**: Each request contains all necessary information 3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors 4. **Version Your API**: Plan for breaking changes from day one 5. **Pagination**: Always paginate large collections 6. **Rate Limiting**: Protect your API with rate limits 7. **Documentation**: Use OpenAPI/Swagger for interactive docs ### GraphQL APIs 1. **Schema First**: Design schema before writing resolvers 2. **Avoid N+1**: Use DataLoaders for efficient data fetching 3. **Input Validation**: Validate at schema and resolver levels 4. **Error Handling**: Return structured errors in mutation payloads 5. **Pagination**: Use cursor-based pagination (Relay spec) 6. **Deprecation**: Use @deprecated` directive for gradual migration 7. Monitoring: Track query complexity and execution time ## Common Pitfalls - Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders - Breaking Changes: Version APIs or use deprecation strategies - Inconsistent Error Formats: Standardize error responses - Missing Rate Limits: APIs without limits are vulnerable to abuse - Poor Documentation: Undocumented APIs frustrate developers - Ignoring HTTP Semantics: POST for idempotent operations breaks expectations - Tight Coupling: API structure shouldn't mirror database schema