Design RESTful and GraphQL APIs with endpoint naming, versioning, error handling, and pagination.
npx skills add https://github.com/Zate/cc-plugins --skill api-design-zate
Please help me install this Agent Skill. Skill: api-design Source: https://github.com/Zate/cc-plugins/tree/main/plugins/devloop/skills/api-design Command: npx skills add https://github.com/Zate/cc-plugins --skill api-design-zate
Poorly designed APIs lead to developer frustration, integration challenges, and scalability issues. This Skill provides best practices for designing clean, consistent, and developer-friendly APIs that stand the test of time.
Design a RESTful API endpoint for retrieving a list of users, including pagination, filtering by status, and sorting by name.
High-intent search queries and answers about installing and using this skill.
REST API design uses resource-based URL structures with standard HTTP methods: GET for retrieval, POST for creation, PUT/PATCH for updates, and DELETE for removal. Follow consistent naming conventions, use plural nouns for collections, and return appropriate status codes (200, 201, 400, 404, 500) to create predictable, intuitive endpoints developers can work with immediately.
Pagination strategies include offset-based, cursor-based, and keyset pagination. Cursor and keyset pagination perform better at scale and handle data changes reliably. Include metadata like total count, next/previous links, and configurable page size limits in responses to let clients retrieve large datasets efficiently without duplicates or gaps.
REST excels for simple, resource-driven APIs with fixed response shapes and broad client compatibility. GraphQL suits clients needing flexible queries, multiple data types in one request, and reduced over-fetching. Choose REST for public APIs and GraphQL for internal or client-heavy systems where query flexibility justifies added complexity.
Common API authentication patterns include Bearer tokens for stateless requests, API keys for service-to-service calls, and OAuth 2.0 for delegated user access. Select Bearer tokens for simplicity and scalability, API keys for internal tools, and OAuth 2.0 when third-party applications need user-level permissions without storing credentials.
API versioning strategies include URL path versioning (/v1/users), query parameters (?version=1), and header-based versioning. URL versioning is most discoverable and cache-friendly. Plan deprecation timelines, document breaking changes clearly, and maintain at least two versions simultaneously to give clients time to migrate.
OpenAPI/Swagger documentation provides machine-readable API contracts that generate interactive explorers, client SDKs, and server stubs automatically. Documentation reduces integration friction, enables testing, and serves as a single source of truth for endpoint contracts, parameters, responses, and authentication requirements across teams.
mohitmishra786Design system architecture, select technology stacks, and define API contracts.
mgd34msuGenerate TypeScript types and client SDKs from OpenAPI 3.1 specifications.
SoftSystemsStudioEnforce standardized Express API endpoint patterns with middleware and Zod validation.
JochenYangDesign REST, GraphQL, and gRPC APIs with OpenAPI generation and versioning strategies.
