api-design-principles

REST API design requires consistent resource modeling, HTTP semantics, and clear versioning strategies. This skill provides structured guidelines for naming conventions, request/response patterns, and deprecation policies to ensure scalability and maintainability across distributed teams.

API versioning can use URL paths, headers, or query parameters, each with trade-offs. This skill covers versioning strategies, compatibility policies, and migration paths to help you choose the approach that minimizes client disruption while supporting evolution.

GraphQL schema design follows schema-first principles with clear naming, pagination patterns, and error handling conventions. This skill provides design patterns and best practices to build intuitive, self-documenting GraphQL APIs that reduce developer friction.

Effective API documentation covers resource definitions, request/response examples, error codes, pagination, and authentication details. This skill includes templates and documentation practices for both REST and GraphQL to ensure clarity and usability.

These principles apply to both new APIs and audits of existing ones. The skill provides standardized patterns and migration paths so teams can incrementally align legacy APIs with best practices without full rewrites.

Error handling and pagination differ between REST and GraphQL but both require predictable, documented patterns. This skill covers practical approaches for status codes, error payloads, offset/cursor pagination, and field-level errors to maintain consistency within each paradigm.