| name | API Design |
| description | Design RESTful APIs with endpoint specifications, request/response schemas, and error handling |
| version | 1.0 |
| tags | ["engineering","backend","design"] |
| complexity | intermediate |
| requires_tools | [] |
Process
- Identify resources — Map the domain entities to REST resources (nouns, not verbs)
- Define endpoints — GET, POST, PUT/PATCH, DELETE for each resource
- Design request/response schemas — JSON payloads with field types, required/optional
- Error handling — Standard error response format with HTTP status codes
- Pagination & filtering — Cursor or offset-based pagination, query parameters for filtering
- Authentication — Specify auth method (API key, Bearer token, OAuth)
- Versioning — URL prefix (/api/v1) or header-based versioning strategy
Output Format
For each endpoint, provide:
### [METHOD] /api/resource
Description: What this endpoint does
Auth: Required / Optional
Request Body:
{ field: type (required/optional) }
Response 200:
{ field: type }
Error Responses:
400: Validation error
404: Resource not found
Guidelines
- Use plural nouns for collections (
/users, not /user)
- Use nested routes for relationships (
/users/{id}/orders)
- Keep payloads flat — avoid deeply nested objects
- Return created/updated resource in response body
- Use consistent field naming (camelCase or snake_case, not both)
- Include pagination metadata in list responses (
total, page, per_page)
- Document rate limits if applicable
