/api-patterns

name: api-patterns
description: "API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination."
risk: none
source: community
date_added: "2026-02-27"

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 | |------|-------------|--------------| | `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type | | `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API | | `response.md` | Envelope pattern, error format, pagination | Response structure | | `graphql.md` | Schema design, when to use, security | Considering GraphQL | | `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects | | `versioning.md` | URI/Header/Query versioning | API evolution planning | | `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection | | `rate-limiting.md` | Token bucket, sliding window | API protection | | `documentation.md` | OpenAPI/Swagger best practices | Documentation | | `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |

---

🔗 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?**

---

❌ Anti-Patterns

**DON'T:**

• Default to REST for everything
• Use verbs in REST endpoints (/getUsers)
• Return inconsistent response formats
• Expose internal errors to clients
• Skip rate limiting

**DO:**

• Choose API style based on context
• Ask about client requirements
• Document thoroughly
• Use appropriate status codes

---

Script

| Script | Purpose | Command | |--------|---------|---------| | `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.