api-patterns

SKILL.md

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.

26:["$