api-design

The api-design skill provides a structured framework for architecting robust, scalable, and standardized backend services. It is designed for backend engineers and system architects who need to ensure API consistency, maintainability, and clear communication between client and server components. Whether you are building a new microservice, implementing a GraphQL schema, or refactoring existing REST endpoints, this skill guides you through industry-standard design patterns to reduce technical debt and accelerate development velocity.

• Resource-oriented architecture: Enforces the use of plural nouns and logical resource nesting, strictly avoiding verbs in URLs to maintain predictable RESTful paths.

• HTTP method alignment: Validates the correct usage of GET, POST, PUT, PATCH, and DELETE verbs while emphasizing idempotency to ensure safe system operations.

• Standardized response patterns: Implements consistent data wrapping, meta-field inclusion for pagination, and uniform error reporting structures using appropriate HTTP status codes.

• Advanced query capabilities: Facilitates the design of robust filtering, sorting, field selection, and search mechanisms using standardized query parameters.

• API lifecycle management: Supports effective versioning strategies, including URL-based and header-based versioning, and provides templates for OpenAPI 3.0/Swagger documentation.

• GraphQL best practices: Offers schema design patterns, input validation, custom error handling, and type-safe mutation structures.

• Typical inputs include technical requirements for a new resource, database schema definitions, or legacy API endpoints requiring modernization.

• Typical outputs include clean route definitions, OpenAPI YAML documentation, JSON response contracts, and implementation blueprints for pagination or authentication handlers.

• Users should adhere to established naming conventions (lowercase/hyphens) to ensure API consistency across the team.

• When implementing complex filters, leverage the provided patterns for range-based filtering (e.g., created_gte, price_min) to maintain predictability.

• Ensure that all error responses provide actionable details, such as error codes and field-level messages, without exposing sensitive internal stack traces or database internals.