| name | api-design |
| description | Review API design — endpoints, types, contracts, error handling, versioning, and consistency. Trigger on /api-design, or when designing or reviewing API specifications. |
| user-invocable | true |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
API Design
Review API contracts for consistency, completeness, and usability.
Review Checklist
1. Naming and structure
- Consistent URL patterns (
/resources, /resources/:id, not mixed conventions)?
- RESTful resource orientation (nouns, not verbs in URL)?
- Consistent pluralization?
- Versioning strategy (
/v1/, header-based, or no versioning)?
2. Request design
- Required vs optional fields clearly defined?
- Input validation rules documented?
- Content-Type handling consistent?
- Pagination strategy for list endpoints? (cursor vs offset)
- Filtering/searching parameters consistent?
3. Response design
- Consistent response structure (same envelope for success/error)?
- Error format consistent (code, message, details)?
- HTTP status codes used appropriately? (200, 201, 204, 400, 401, 403, 404, 409, 422, 500)
- No sensitive data in responses?
4. Type safety
- Request/response types fully defined?
- Edge cases covered (empty lists, optional fields, nullable fields)?
- Breaking changes in types?
- Backwards compatibility maintained?
5. Error handling
- Every error path documented?
- Error messages actionable for the caller?
- Rate limiting strategy?
- Idempotency for mutating endpoints?
6. Performance
- N+1 query risks in the implementation?
- Response sizes reasonable?
- Caching strategy defined?
- Batch operations where appropriate?
Experience Log
This skill learns from experience. Mechanism:
- Read
.claude/experience/api-design.md at skill start to benefit from past lessons.
- Write to
.claude/experience/api-design.md after use if you learned something new.
- Format:
YYYY-MM-DD: <lesson> — one line per entry.
- Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.
