Skill: API DesignerAI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.
Design consistent, RESTful APIs with versioning, documentation, and error handling.
RESTful Conventions
| Method | Endpoint | Purpose | Response |
|---|---|---|---|
| GET | /users | List | 200 + array |
| GET | /users/:id | Get one | 200 / 404 |
| POST | /users | Create | 201 + created |
| PUT | /users/:id | Replace | 200 / 404 |
| PATCH | /users/:id | Update | 200 / 404 |
| DELETE | /users/:id | Delete | 204 / 404 |
Nested: GET /users/:userId/orders
Naming
- Resources: plural nouns (
/users,/orders) - Query params: snake_case (
page_size) - Request/Response bodies: camelCase
Versioning: URL path /api/v1/... (recommended).
Response Format
Success: { "data": {...}, "meta": {...} }
List: Add meta: { page, pageSize, total, totalPages }
Error: { "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": {...} } }
Status Codes
| Code | When |
|---|---|
| 200 | Successful GET/PUT/PATCH |
| 201 | Successful POST |
| 204 | Successful DELETE |
| 400/422 | Invalid input / validation |
| 401/403 | No auth / no permission |
| 404/409 | Not found / conflict |
| 429 | Rate limited |
| 500 | Unexpected error |
Pagination
Offset: ?page=2&page_size=20 (simple, slow on large sets)
Cursor: ?cursor=abc&limit=20 (consistent, fast, no page jump)
Filtering & Sorting
GET /users?status=active&sort=created_at:desc&q=john&page=1&page_size=20
Design Workflow
- Define resources and relationships → 2. Choose versioning strategy → 3. Define endpoints with RESTful naming → 4. Specify response/error schemas → 5. Add pagination, filtering, sorting → 6. Document with OpenAPI → 7. Add rate limiting headers
Checklist
RESTful naming, consistent response format, proper status codes, pagination for lists, error codes, versioning, OpenAPI docs, rate limiting headers.
Related Rules
rules/agent/api-design-rules.md— enforcement checklist (short form of this skill)rules/core/simplicity-over-complexity.md— favor flat resources over nested hierarchies, reject premature GraphQL when REST fits, no speculative "future-proofing" fieldsrules/agent/structured-data-schema.md— consistent schema across endpointsrules/agent/error-handling-standard.md— uniform error envelope