API Design Patterns

Conventions and best practices for designing consistent, developer-friendly REST APIs.

When to Activate

• Before writing any implementation — design the contract first, code second
• Designing new API endpoints or changing existing ones
• Reviewing existing API contracts for consistency
• Adding pagination, filtering, or sorting — see skill api-pagination-filtering
• Implementing error handling for APIs
• Planning API versioning strategy
• Building public or partner-facing APIs

For the full Contract-First workflow (spec writing, code generation, CI breaking-change detection, Pact): see skill api-contract. For API documentation production — platform choice (Mintlify, Docusaurus, Redoc, Scalar), OpenAPI descriptions/examples, interactive playground, changelog automation, Vale prose linting, and Divio structure: see skill api-docs-patterns.

Contract-First Principle