api-patterns

xenitV1 的头像作者 xenitV1

包括资源命名、HTTP 方法、状态码、版本控制、分页和响应格式在内的 REST API 设计模式。在设计或实现 API 时使用。

📖 中文导读:包括资源命名、HTTP 方法、状态码、版本控制、分页和响应格式在内的 REST API 设计模式。在设计或实现 API 时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: api-patterns description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. allowed-tools: Read, Write, Edit, Glob, Grep

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

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>