API Patterns
API design principles and decision-making for 2025. Learn to THINK, not copy fixed patterns.
🎯 Selective Reading Rule
Read ONLY files relevant to the request! Check the content map, find what you need.
📑 Content Map
| File | Description | When to Read |
|---|---|---|
references/api-style.md | REST vs GraphQL vs tRPC decision tree | Choosing API type |
references/rest.md | Resource naming, HTTP methods, status codes | Designing REST API |
references/response.md | Envelope pattern, error format, pagination | Response structure |
references/graphql.md | Schema design, when to use, security | Considering GraphQL |
references/trpc.md | TypeScript monorepo, type safety | TS fullstack projects |
references/versioning.md | URI/Header/Query versioning | API evolution planning |
references/auth.md | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
references/rate-limiting.md | Token bucket, sliding window | API protection |
references/documentation.md | OpenAPI/Swagger best practices | Documentation |
references/security-testing.md | OWASP API Top 10, auth/authz testing | Security audits |
🚀 Quick Decision
code
Who are the API consumers? │ ├── Public API / Multiple platforms ────→ REST + OpenAPI ├── Complex data / Multiple frontends ──→ GraphQL ├── TypeScript monorepo ────────────────→ tRPC ├── Real-time / Event-driven ───────────→ WebSocket + AsyncAPI └── Internal microservices ─────────────→ gRPC or REST
First question ALWAYS: ¿Quién va a consumir esta API?
🔗 Related Skills
| Need | Skill |
|---|---|
| API implementation | @[skills/backend-development] |
| Data structure | @[skills/database-design] |
| Security details | @[skills/security-hardening] |
✅ Decision Checklist
Before designing an API:
- • Asked user about API consumers?
- • Chosen API style for THIS context? (REST/GraphQL/tRPC)
- • Defined consistent response format?
- • Planned versioning strategy?
- • Considered authentication needs?
- • Planned rate limiting?
- • Documentation approach defined?
⚠️ Racionalizaciones Comunes
| Excusa | Realidad |
|---|---|
| "Siempre usamos REST" | Evalúa consumidores primero - tRPC o GraphQL podrían ser mejores |
| "GraphQL es overkill" | Para apps con datos complejos, reduce overfetching significativamente |
| "No necesitamos versionado" | Los clientes romperán sin aviso cuando hagas breaking changes |
| "Rate limiting después" | Implementar desde día 1 es 10x más fácil que retrofitting |
| "Los errores ya se manejan" | Sin formato consistente, el frontend sufre |
❌ Anti-Patterns
NUNCA:
- •Defaults a REST sin evaluar contexto
- •Verbos en endpoints REST (
/getUsers→/users) - •Formatos de respuesta inconsistentes
- •Exponer errores internos al cliente
- •Saltear rate limiting
SIEMPRE:
- •Elegir estilo API basado en consumidores
- •Preguntar requisitos del cliente
- •Documentar exhaustivamente
- •Usar status codes apropiados
Script
| Script | Purpose | Command |
|---|---|---|
scripts/api_validator.py | API endpoint validation | python scripts/api_validator.py <project_path> |