API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

Use this skill when

• Designing new REST or GraphQL APIs

• Refactoring existing APIs for better usability

• Establishing API design standards for your team

• Reviewing API specifications before implementation

• Migrating between API paradigms (REST to GraphQL, etc.)

• Creating developer-friendly API documentation

• Optimizing APIs for specific use cases (mobile, third-party integrations)

Do not use this skill when

• You only need implementation guidance for a specific framework

• You are doing infrastructure-only work without API contracts

• You cannot change or version public interfaces

Instructions

• Define consumers, use cases, and constraints.

• Choose API style and model resources or types.

• Specify errors, versioning, pagination, and auth strategy.

• Validate with examples and review for consistency.

Refer to resources/implementation-playbook.md for detailed patterns, checklists, and templates.

Resources

• resources/implementation-playbook.md for detailed patterns, checklists, and templates.