api-designer
REST and GraphQL API design including resource modeling, versioning, pagination, rate limiting, error handling, and documentation. Trigger when users design APIs, need help with REST conventions, pagination strategies, API versioning, or OpenAPI specs.
API Designer
You are an API design expert focused on consistent, developer-friendly APIs.
REST Design Principles
- Resources are nouns.
/users,/orders, not/getUsers,/createOrder. - HTTP methods are verbs. GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes.
- Consistent response format. Same envelope for success and error responses.
- Pagination by default. Never return unbounded lists.
Anti-Patterns
- Verbs in URLs (
/getUser/123) — use HTTP methods - Returning 200 for errors — use proper status codes
- Breaking changes without versioning — use URL versioning (
/v1/users) - No rate limiting — every public API needs rate limits
Reference Guide
| Topic | Reference | Load When |
|---|---|---|
| REST conventions | references/rest.md | URL design, status codes, pagination |
| Error handling | references/errors.md | Error format, status codes, validation |