API Patterns

1---
2name: api-patterns
3description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
4allowed-tools: Read, Write, Edit, Glob, Grep
5---
6 
7# API Patterns
8 
9> API design principles and decision-making for 2025.
10> **Learn to THINK, not copy fixed patterns.**
11 
12## 🎯 Selective Reading Rule
13 
14**Read ONLY files relevant to the request!** Check the content map, find what you need.
15 
16---
17 
18## 📑 Content Map
19 
20| File | Description | When to Read |
21|------|-------------|--------------|
22| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
23| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
24| `response.md` | Envelope pattern, error format, pagination | Response structure |
25| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
26| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
27| `versioning.md` | URI/Header/Query versioning | API evolution planning |
28| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
29| `rate-limiting.md` | Token bucket, sliding window | API protection |
30| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
31| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
32 
33---
34 
35## 🔗 Related Skills
36 
37| Need | Skill |
38|------|-------|
39| API implementation | `@[skills/backend-development]` |
40| Data structure | `@[skills/database-design]` |
41| Security details | `@[skills/security-hardening]` |
42 
43---
44 
45## ✅ Decision Checklist
46 
47Before designing an API:
48 
49- [ ] **Asked user about API consumers?**
50- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
51- [ ] **Defined consistent response format?**
52- [ ] **Planned versioning strategy?**
53- [ ] **Considered authentication needs?**
54- [ ] **Planned rate limiting?**
55- [ ] **Documentation approach defined?**
56 
57---
58 
59## ❌ Anti-Patterns
60 
61**DON'T:**
62- Default to REST for everything
63- Use verbs in REST endpoints (/getUsers)
64- Return inconsistent response formats
65- Expose internal errors to clients
66- Skip rate limiting
67 
68**DO:**
69- Choose API style based on context
70- Ask about client requirements
71- Document thoroughly
72- Use appropriate status codes
73 
74---
75 
76## Script
77 
78| Script | Purpose | Command |
79|--------|---------|---------|
80| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
81 
82