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 resourcesPUT: Replace entire resource (idempotent)PATCH: Partial resource updatesDELETE: 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
- Consistent Naming: Use plural nouns for collections (
/users, not/user) - Stateless: Each request contains all necessary information
- Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
- Version Your API: Plan for breaking changes from day one
- Pagination: Always paginate large collections
- Rate Limiting: Protect your API with rate limits
- Documentation: Use OpenAPI/Swagger for interactive docs
GraphQL APIs
- Schema First: Design schema before writing resolvers
- Avoid N+1: Use DataLoaders for efficient data fetching
- Input Validation: Validate at schema and resolver levels
- Error Handling: Return structured errors in mutation payloads
- Pagination: Use cursor-based pagination (Relay spec)
- Deprecation: Use
@deprecateddirective for gradual migration - 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