api-design

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

1. Identify resources — Map the domain entities to REST resources (nouns, not verbs)
2. Define endpoints — GET, POST, PUT/PATCH, DELETE for each resource
3. Design request/response schemas — JSON payloads with field types, required/optional
4. Error handling — Standard error response format with HTTP status codes
5. Pagination & filtering — Cursor or offset-based pagination, query parameters for filtering
6. Authentication — Specify auth method (API key, Bearer token, OAuth)
7. 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