Design Scalable REST and GraphQL APIs

This skill covers REST and GraphQL API design principles for building intuitive, scalable, and maintainable APIs. Its process: define consumers, use cases, and constraints; choose an API style and model resources or types; specify errors, versioning, pagination, and auth strategy; and validate with examples and a consistency review. A detailed implementation playbook (resources/implementation-playbook.md) covers deeper patterns, checklists, and templates.

Use this when designing new REST or GraphQL APIs, refactoring existing APIs for better usability, establishing API design standards for a team, reviewing API specifications before implementation, migrating between API paradigms (REST to GraphQL), creating developer-friendly API documentation, or optimizing an API for a specific use case (mobile clients, third-party integrations).

Not the right skill if you only need implementation guidance for a specific framework, if the work is infrastructure-only with no API contract involved, or if you can't change or version the public interface at all - there's nothing to design if the contract is fixed.

Inputs: the API's target consumers, use cases, and constraints (mobile, third-party, internal).

Outputs: a chosen API style (REST or GraphQL) with modeled resources/types, defined error handling, versioning strategy, pagination approach, and auth strategy - validated against concrete usage examples for consistency.

Applies to REST and GraphQL API paradigms generally, independent of a specific framework or vendor.

API designers, backend engineers, and teams establishing or reviewing API design standards who need a structured process from consumer definition through versioning and auth strategy.