API Design Principles

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## Use this skill when
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## Do not use this skill when
21 
22- You only need implementation guidance for a specific framework
23- You are doing infrastructure-only work without API contracts
24- You cannot change or version public interfaces
25 
26## Instructions
27 
281. Define consumers, use cases, and constraints.
292. Choose API style and model resources or types.
303. Specify errors, versioning, pagination, and auth strategy.
314. Validate with examples and review for consistency.
32 
33Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.
34 
35## Resources
36 
37- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.
38