api-design-principles

This skill provides a comprehensive framework for designing professional-grade APIs, focusing on industry-standard paradigms like RESTful resource-oriented architecture and GraphQL schema-first development. It is intended for backend engineers, system architects, and technical leads who need to establish API design standards, perform design reviews, or refactor existing interfaces for better usability and maintainability. Whether you are building new services or migrating between paradigms, this skill ensures your API remains intuitive, performant, and developer-friendly.

• Resource-oriented architecture: Applying nouns for resources and utilizing proper HTTP verb semantics (GET, POST, PUT, PATCH, DELETE) to maintain consistent API behavior.

• GraphQL mastery: Implementing schema-first design, efficient query structures, mutations, and real-time subscriptions to enable client-side data fetching precision.

• Versioning strategies: Implementing robust URL, header, or query parameter versioning to ensure backward compatibility and smooth transitions.

• Advanced patterns: Applying HATEOAS, pagination, filtering, and standardized error handling using HTTP status codes to improve client integration and debugging.

• Documentation standards: Creating self-documenting APIs that emphasize clarity, strong typing, and intuitive hierarchies to delight third-party developers.

• Use this skill during the architectural design phase of a project, before writing endpoint logic or defining data models.

• Ideal for auditing existing specifications to identify common pitfalls like action-oriented naming or inconsistent error responses.

• Supports Pydantic-based validation and FastAPI-style implementation patterns to translate design principles into high-quality code.

• Inputs typically include technical requirements, domain models, or problematic existing endpoints; outputs are refined API specifications, design patterns, or structured feedback for developers.

• Constraints: Focuses on backend API design; ensure adherence to your specific framework requirements (e.g., FastAPI, Apollo) while maintaining the universal design principles provided here.