api-design
Design API endpoints, schemas, and contracts. Use when defining public interfaces or data models.
When & Why to Use This Skill
The API Design skill streamlines the creation of robust interface contracts by defining RESTful endpoints, request/response schemas, and standardized error handling. It ensures data consistency and architectural integrity when building public APIs or internal microservices, following industry best practices for versioning and documentation.
Use Cases
- Microservices Architecture: Defining clear communication contracts and data models between distributed services to ensure seamless integration.
- Public API Development: Designing developer-friendly endpoints and comprehensive JSON schemas for external third-party integrations.
- Legacy System Modernization: Refactoring outdated interfaces into standardized RESTful APIs with consistent naming conventions and error codes.
- Technical Documentation: Generating structured API specifications that serve as a single source of truth for frontend and backend teams.
| name | api-design |
|---|---|
| description | Design API endpoints, schemas, and contracts. Use when defining public interfaces or data models. |
API Design
Define the interface contracts for APIs, including endpoints, request/response schemas, and error handling.
Process
- Review spec.md and architecture.md
- Define endpoints and HTTP methods
- Design request and response schemas
- Define error responses and codes
- Consider versioning strategy
Output
Create api-design.md using the template in templates/api-design.md.
Tips
- Use consistent naming conventions
- Design for backwards compatibility
- Include example payloads
- Document rate limits if applicable
- Consider pagination for list endpoints