Skip to main content
This skill teaches API design principles and decision-making for 2025. Learn to THINK about API architecture, not copy fixed patterns.

​
What This Skill Provides

The API Patterns skill provides comprehensive API design principles covering REST, GraphQL, and tRPC. It emphasizes context-driven decision-making over copying templates.

​
Core Knowledge Areas

API Style Selection

Decision trees for choosing REST vs GraphQL vs tRPC based on use case and constraints

REST Design

Resource naming, HTTP methods, status codes, and RESTful principles

Response Patterns

Envelope patterns, error formats, pagination strategies, and consistency

Versioning

URI, header, and query parameter versioning strategies

Authentication

JWT, OAuth, Passkey, and API key patterns

Security

OWASP API Top 10, rate limiting, auth/authz testing

​
When This Skill Is Loaded

Agents load this skill when:
  • Designing API architectures
  • Choosing between REST, GraphQL, or tRPC
  • Defining API response formats
  • Planning API versioning strategies
  • Implementing authentication patterns
  • Setting up rate limiting
  • Documenting APIs (OpenAPI/Swagger)
  • Conducting security audits
The skill uses selective reading - agents only load files relevant to the specific API design question at hand.

​
Use Cases

​
API Style Selection

Decision framework for choosing the right API pattern:

REST

Use when:
  • Public API
  • Broad compatibility needed
  • Simple CRUD operations
  • Caching is important
  • Standard HTTP semantics

GraphQL

Use when:
  • Complex queries needed
  • Multiple client types
  • Flexible data fetching
  • Avoiding over/under-fetching
  • Real-time subscriptions

tRPC

Use when:
  • TypeScript monorepo
  • Internal APIs
  • End-to-end type safety
  • Rapid development
  • Shared types across stack

​
Response Format Design

Consistent response structures:
  • Success responses - Standard data envelope
  • Error responses - Error codes, messages, details
  • Pagination - Offset, cursor, or page-based
  • Metadata - Request IDs, timestamps, versioning

​
Versioning Strategies

MethodExampleUse When
URI/v1/usersBreaking changes, clear separation
HeaderAccept: application/vnd.api.v2+jsonGradual migration
Query/users?version=2Optional feature flags

​
Authentication Patterns

JWT

Stateless, scalable, good for microservices

OAuth 2.0

Third-party authorization, social login

Passkey/WebAuthn

Modern, passwordless, phishing-resistant

API Keys

Simple, service-to-service authentication

​
Key Principles

​
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?

​
REST Principles

  • Resources, not actions - Use nouns (/users), not verbs (/getUsers)
  • HTTP methods semantics - GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
  • Proper status codes - 200 (OK), 201 (Created), 400 (Bad Request), 404 (Not Found), 500 (Server Error)
  • Stateless - Each request contains all necessary information
  • Cacheable - Use appropriate cache headers

​
GraphQL Principles

  • Schema-first design - Define types before implementation
  • Resolver organization - Separate data fetching logic
  • N+1 prevention - Use DataLoader for batching
  • Authorization - Check permissions in resolvers
  • Depth limiting - Prevent overly complex queries

​
tRPC Principles

  • Type safety - End-to-end TypeScript types
  • Procedure organization - Group related operations
  • Middleware - Authentication, logging, validation
  • Context - Share request data across procedures

Node.js Best Practices

Framework selection and async patterns

Python Patterns

FastAPI and Django API implementation

Rust Pro

High-performance API services with axum

​
Which Agents Use This Skill

Backend Specialist

The Backend Specialist loads this skill for all API design and implementation work. It’s used alongside runtime-specific skills (Node.js, Python, Rust) for implementation details.
The Backend Specialist combines this skill with nodejs-best-practices, python-patterns, or rust-pro depending on the chosen runtime and framework.

​
Anti-Patterns to Avoid

Don’t:
  • Default to REST for everything without considering alternatives
  • Use verbs in REST endpoints (/getUsers, /createUser)
  • Return inconsistent response formats
  • Expose internal errors to clients
  • Skip rate limiting
  • Forget to document APIs
  • Use GET requests for mutations
  • Return HTML errors for JSON APIs
Do:
  • Choose API style based on context and requirements
  • Ask about client requirements before deciding
  • Document thoroughly (OpenAPI, GraphQL schema)
  • Use appropriate HTTP status codes
  • Validate all inputs at API boundary
  • Implement proper error handling
  • Plan for versioning from the start

​
Content Organization

The skill contains detailed reference files:
  1. api-style.md - REST vs GraphQL vs tRPC decision tree
  2. rest.md - Resource naming, HTTP methods, status codes
  3. response.md - Envelope pattern, error format, pagination
  4. graphql.md - Schema design, when to use, security
  5. trpc.md - TypeScript monorepo, type safety patterns
  6. versioning.md - URI/Header/Query versioning strategies
  7. auth.md - JWT, OAuth, Passkey, API Keys
  8. rate-limiting.md - Token bucket, sliding window algorithms
  9. documentation.md - OpenAPI/Swagger best practices
  10. security-testing.md - OWASP API Top 10, testing strategies
Agents load only the relevant files based on the specific API design question or task.

​
Validation Script

API Validator

The skill includes an API endpoint validation script:
python scripts/api_validator.py <project_path>
Automatically checks API implementations for common issues and best practice violations.

​
Security Considerations

​
OWASP API Security Top 10

  • Broken object level authorization
  • Broken authentication
  • Broken object property level authorization
  • Unrestricted resource consumption
  • Broken function level authorization
  • Unrestricted access to sensitive flows
  • Server-side request forgery
  • Security misconfiguration
  • Improper inventory management
  • Unsafe consumption of APIs
All API designs should consider these security risks from the start, not as an afterthought.

​
Rate Limiting Patterns

Token Bucket

Allows bursts, smooth traffic over time. Good for APIs with variable load.

Sliding Window

Precise rate limiting, no burst allowance. Good for strict rate control.
Remember: API patterns are about decision-making for YOUR specific context. Every API deserves consideration of its unique requirements, clients, and constraints.

Build docs developers (and LLMs) love

Get started for freeTalk to us