1---
2name: api-design-principles
3description: 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.
4---
5 
6# API Design Principles
7 
8Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
9 
10## When to Use This Skill
11 
12- Designing new REST or GraphQL APIs
13- Refactoring existing APIs for better usability
14- Establishing API design standards for your team
15- Reviewing API specifications before implementation
16- Migrating between API paradigms (REST to GraphQL, etc.)
17- Creating developer-friendly API documentation
18- Optimizing APIs for specific use cases (mobile, third-party integrations)
19 
20## Core Concepts
21 
22### 1. RESTful Design Principles
23 
24**Resource-Oriented Architecture**
25 
26- Resources are nouns (users, orders, products), not verbs
27- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
28- URLs represent resource hierarchies
29- Consistent naming conventions
30 
31**HTTP Methods Semantics:**
32 
33- `GET`: Retrieve resources (idempotent, safe)
34- `POST`: Create new resources
35- `PUT`: Replace entire resource (idempotent)
36- `PATCH`: Partial resource updates
37- `DELETE`: Remove resources (idempotent)
38 
39### 2. GraphQL Design Principles
40 
41**Schema-First Development**
42 
43- Types define your domain model
44- Queries for reading data
45- Mutations for modifying data
46- Subscriptions for real-time updates
47 
48**Query Structure:**
49 
50- Clients request exactly what they need
51- Single endpoint, multiple operations
52- Strongly typed schema
53- Introspection built-in
54 
55### 3. API Versioning Strategies
56 
57**URL Versioning:**
58 
59```
60/api/v1/users
61/api/v2/users
62```
63 
64**Header Versioning:**
65 
66```
67Accept: application/vnd.api+json; version=1
68```
69 
70**Query Parameter Versioning:**
71 
72```
73/api/users?version=1
74```
75 
76## Detailed patterns and worked examples
77 
78Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
79 
80## Best Practices
81 
82### REST APIs
83 
841. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`)
852. **Stateless**: Each request contains all necessary information
863. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors
874. **Version Your API**: Plan for breaking changes from day one
885. **Pagination**: Always paginate large collections
896. **Rate Limiting**: Protect your API with rate limits
907. **Documentation**: Use OpenAPI/Swagger for interactive docs
91 
92### GraphQL APIs
93 
941. **Schema First**: Design schema before writing resolvers
952. **Avoid N+1**: Use DataLoaders for efficient data fetching
963. **Input Validation**: Validate at schema and resolver levels
974. **Error Handling**: Return structured errors in mutation payloads
985. **Pagination**: Use cursor-based pagination (Relay spec)
996. **Deprecation**: Use `@deprecated` directive for gradual migration
1007. **Monitoring**: Track query complexity and execution time
101 
102## Common Pitfalls
103 
104- **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders
105- **Breaking Changes**: Version APIs or use deprecation strategies
106- **Inconsistent Error Formats**: Standardize error responses
107- **Missing Rate Limits**: APIs without limits are vulnerable to abuse
108- **Poor Documentation**: Undocumented APIs frustrate developers
109- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations
110- **Tight Coupling**: API structure shouldn't mirror database schema
111