1# API Design Checklist
2 
3## Pre-Implementation Review
4 
5### Resource Design
6 
7- [ ] Resources are nouns, not verbs
8- [ ] Plural names for collections
9- [ ] Consistent naming across all endpoints
10- [ ] Clear resource hierarchy (avoid deep nesting >2 levels)
11- [ ] All CRUD operations properly mapped to HTTP methods
12 
13### HTTP Methods
14 
15- [ ] GET for retrieval (safe, idempotent)
16- [ ] POST for creation
17- [ ] PUT for full replacement (idempotent)
18- [ ] PATCH for partial updates
19- [ ] DELETE for removal (idempotent)
20 
21### Status Codes
22 
23- [ ] 200 OK for successful GET/PATCH/PUT
24- [ ] 201 Created for POST
25- [ ] 204 No Content for DELETE
26- [ ] 400 Bad Request for malformed requests
27- [ ] 401 Unauthorized for missing auth
28- [ ] 403 Forbidden for insufficient permissions
29- [ ] 404 Not Found for missing resources
30- [ ] 422 Unprocessable Entity for validation errors
31- [ ] 429 Too Many Requests for rate limiting
32- [ ] 500 Internal Server Error for server issues
33 
34### Pagination
35 
36- [ ] All collection endpoints paginated
37- [ ] Default page size defined (e.g., 20)
38- [ ] Maximum page size enforced (e.g., 100)
39- [ ] Pagination metadata included (total, pages, etc.)
40- [ ] Cursor-based or offset-based pattern chosen
41 
42### Filtering & Sorting
43 
44- [ ] Query parameters for filtering
45- [ ] Sort parameter supported
46- [ ] Search parameter for full-text search
47- [ ] Field selection supported (sparse fieldsets)
48 
49### Versioning
50 
51- [ ] Versioning strategy defined (URL/header/query)
52- [ ] Version included in all endpoints
53- [ ] Deprecation policy documented
54 
55### Error Handling
56 
57- [ ] Consistent error response format
58- [ ] Detailed error messages
59- [ ] Field-level validation errors
60- [ ] Error codes for client handling
61- [ ] Timestamps in error responses
62 
63### Authentication & Authorization
64 
65- [ ] Authentication method defined (Bearer token, API key)
66- [ ] Authorization checks on all endpoints
67- [ ] 401 vs 403 used correctly
68- [ ] Token expiration handled
69 
70### Rate Limiting
71 
72- [ ] Rate limits defined per endpoint/user
73- [ ] Rate limit headers included
74- [ ] 429 status code for exceeded limits
75- [ ] Retry-After header provided
76 
77### Documentation
78 
79- [ ] OpenAPI/Swagger spec generated
80- [ ] All endpoints documented
81- [ ] Request/response examples provided
82- [ ] Error responses documented
83- [ ] Authentication flow documented
84 
85### Testing
86 
87- [ ] Unit tests for business logic
88- [ ] Integration tests for endpoints
89- [ ] Error scenarios tested
90- [ ] Edge cases covered
91- [ ] Performance tests for heavy endpoints
92 
93### Security
94 
95- [ ] Input validation on all fields
96- [ ] SQL injection prevention
97- [ ] XSS prevention
98- [ ] CORS configured correctly
99- [ ] HTTPS enforced
100- [ ] Sensitive data not in URLs
101- [ ] No secrets in responses
102 
103### Performance
104 
105- [ ] Database queries optimized
106- [ ] N+1 queries prevented
107- [ ] Caching strategy defined
108- [ ] Cache headers set appropriately
109- [ ] Large responses paginated
110 
111### Monitoring
112 
113- [ ] Logging implemented
114- [ ] Error tracking configured
115- [ ] Performance metrics collected
116- [ ] Health check endpoint available
117- [ ] Alerts configured for errors
118 
119## GraphQL-Specific Checks
120 
121### Schema Design
122 
123- [ ] Schema-first approach used
124- [ ] Types properly defined
125- [ ] Non-null vs nullable decided
126- [ ] Interfaces/unions used appropriately
127- [ ] Custom scalars defined
128 
129### Queries
130 
131- [ ] Query depth limiting
132- [ ] Query complexity analysis
133- [ ] DataLoaders prevent N+1
134- [ ] Pagination pattern chosen (Relay/offset)
135 
136### Mutations
137 
138- [ ] Input types defined
139- [ ] Payload types with errors
140- [ ] Optimistic response support
141- [ ] Idempotency considered
142 
143### Performance
144 
145- [ ] DataLoader for all relationships
146- [ ] Query batching enabled
147- [ ] Persisted queries considered
148- [ ] Response caching implemented
149 
150### Documentation
151 
152- [ ] All fields documented
153- [ ] Deprecations marked
154- [ ] Examples provided
155- [ ] Schema introspection enabled
156