api-design-principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
API Design Principles
Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
Use this skill when
- 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)
Do not use this skill when
- 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
Instructions
- Define consumers, use cases, and constraints.
- Choose API style and model resources or types.
- Specify errors, versioning, pagination, and auth strategy.
- Validate with examples and review for consistency.
Refer to resources/implementation-playbook.md for detailed patterns, checklists, and templates.
Resources
resources/implementation-playbook.mdfor detailed patterns, checklists, and templates.
Limitations
- 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
Subscribers only
The full skill, its 6 bundled files and every download is included with every paid Complete AI plan.
Details
| Source | community |
|---|---|
| License | — |
| Risk label | safe ("critical" means the skill may run commands or touch files — read before use) |
| Files | SKILL.md, assets/api-design-checklist.md, assets/rest-api-template.py, references/graphql-schema-design.md, references/rest-best-practices.md, resources/implementation-playbook.md |
| Added | 2026-02-27 |
Related skills
api-analyzer
Validates whether an API request is correct based on provided inputs (method, URL, headers, body, auth, query params).
api-and-interface-design
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
api-designer
Generates complete, production-ready REST API endpoint specifications for any system or domain the user describes.
api-documentation-generator
Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices
api-documenter
Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals.
api-fuzzing-bug-bounty
Provide comprehensive techniques for testing REST, SOAP, and GraphQL APIs during bug bounty hunting and penetration testing engagements. Covers vulnerability discovery, authentication bypass, IDOR exploitation, and API-specific attack vectors.