API Designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning...
Install
npx skills add Jeffallan/claude-skills --skill api-designer -g -a claude-code -y- Repository
- Jeffallan/claude-skills12.2k
- Category
- Design
- Updated
- 5d ago
- License
- MIT
- Context cost
- Mediumabout 1,819 tokens
- Runs scripts
- No, instructions only
What it does
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
API Designer
Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.
Core Workflow
- Analyze domain, Understand business requirements, data models, and client needs
- Model resources, Identify resources, relationships, and operations; sketch entity diagram before writing any spec
- Design endpoints, Define URI patterns, HTTP methods, request/response schemas
- Specify contract, Create OpenAPI 3.1 spec; validate before proceeding:
npx @redocly/cli lint openapi.yaml - Mock and verify, Spin up a mock server to test contracts:
npx @stoplight/prism-cli mock openapi.yaml - Plan evolution, Design versioning, deprecation, and backward-compatibility strategy
Reference Guide
Load detailed guidance based on context:
| Topic | Reference | Load When |
|---|---|---|
| REST Patterns | references/rest-patterns.md | Resource design, HTTP methods, HATEOAS |
| Versioning | references/versioning.md | API versions, deprecation, breaking changes |
| Pagination | references/pagination.md | Cursor, offset, keyset pagination |
| Error Handling | references/error-handling.md | Error responses, RFC 7807, status codes |
| OpenAPI | references/openapi.md | OpenAPI 3.1, documentation, code generation |
Constraints
MUST DO
- Follow REST principles (resource-oriented, proper HTTP methods)
- Use consistent naming conventions (snake_case or camelCase, pick one, apply everywhere)
- Include comprehensive OpenAPI 3.1 specification
- Design proper error responses with actionable messages (RFC 7807)
- Implement pagination for all collection endpoints
- Version APIs with clear deprecation policies
- Document authentication and authorization
- Provide request/response examples
