domains / families / software-engineering / api-design-principles

api-design-principles

combined

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards. Principles and checklists for designing and reviewing REST and GraphQL APIs; use when defining or evaluating API contracts (endpoints/schemas), naming, error models, pagination, versioning, and REST vs. GraphQL trade-offs.

When to use

• 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)
• Designing a new REST API contract for CRUD-style resources and you need consistent resource modeling, naming, and HTTP semantics.

When not to use

• 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
• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Skill page

Conflict

The copies overlap on the high-level workflow (define consumers, choose style, model resources, specify errors/versioning/pagination/auth, validate), but they disagree on the level of detail and the concrete artifacts. rmyndharis and sickn33 are nearly identical short procedures that point to a missing `resources/implementation-playbook.md`. LeoYeAI provides a detailed, code-heavy implementation guide with Python/FastAPI examples for pagination, error handling, and HATEOAS. aipoch provides a different, more rigorous workflow focused on contract design, idempotency, and a specific review checklist with `curl` examples. Crowning one would hide the specific implementation patterns in LeoYeAI or the rigorous contract-review workflow in aipoch.