Agent skill · software engineering · aiskillstore
api-design-framework
Use this skill when designing REST, GraphQL, or gRPC APIs. Provides comprehensive API design patterns, versioning strategies, error handling conventions, authentication approaches, and OpenAPI/AsyncAPI templates. Ensures consistent, well-documented, and developer-friendly APIs across all backend services.
Why this skill is useful
Provides specific API design patterns and versioning strategies that the AI wouldn't reliably generate on its own.
What it needs
About 7k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
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: Use hierarchical relationships: Use kebab-case for multi-word resources: HTTP Methods (Verbs) Method Purpose Idempotent Safe Example -------- --------- ------------ ------ --------- GET Retrieve resource(s) Yes Yes GET /users/123 POST Create resource No No POST /users PUT Replace entire resource Yes No PUT /users/123 PATCH Partial update No No PATCH /users/123 DELETE Remove resource Yes No DELETE /users/123 HEAD Metadata only (no body) Yes Yes HEAD /users/123 OPTIONS Allowed methods Yes Yes OPTIONS /users PATCH can be designed to be idempotent Status Codes Success (2xx) 200 OK: Successful GET, PUT, PA …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/api-design-framework