api-design-framework

# API Design Framework ## Overview This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability. **When to use this skill:** - Designing new API endpoints or services - Establishing API conventions for a team or organization - Reviewing API designs for consistency and best practices - Migrating or versioning existing APIs - Creating API documentation (OpenAPI, AsyncAPI) - Choosing between REST, GraphQL, or gRPC ## API Design Principles ### 1. Developer Experience First APIs should be intuitive and self-documenting: - Clear, consistent naming conventions - Predictable behavior and responses - Comprehensive documentation - Helpful error messages ### 2. Consistency Over Cleverness Follow established patterns rather than inventing new ones: - Standard HTTP methods and status codes (REST) - Conventional query structures (GraphQL) - Idiomatic proto definitions (gRPC) ### 3. Evolution Without Breaking Changes Design for change from day one: - API versioning strategy - Backward compatibility considerations - Deprecation policies - Migration paths ### 4. Performance by Design Consider performance implications: - Pagination for large datasets - Filtering and partial responses - Caching strategies - Rate limiting --- ## REST API Design ### Resource Naming Conventions **Use plural nouns for resources:** ``` ✅ GET /user...