API Patterns Reference
Target Spawn
Backend domain work spawned via Agent(general-purpose) with backend instructions - Applies these patterns directly to API implementation and review.
RESTful API Design Conventions
| Principle | Convention | Example |
|---|---|---|
| Resource Naming | Plural nouns, lowercase, kebab-case | /api/v1/user-profiles |
| Collection | GET returns array with pagination | GET /users?page=1&limit=20 |
| Single Resource | GET returns object | GET /users/{id} |
| Create | POST to collection | POST /users |
| Update (full) | PUT to resource | PUT /users/{id} |
| Update (partial) | PATCH to resource | PATCH /users/{id} |
| Delete | DELETE to resource | DELETE /users/{id} |
| Nested Resources | Max 2 levels deep | /users/{id}/posts |
| Filtering | Query params | ?status=active&role=admin |
| Sorting | Sort param | ?sort=-created_at,name |
| Versioning | URL prefix | /api/v1/, /api/v2/ |
HTTP Status Code Guide
| Category | Code | When to Use |
|---|---|---|
| Success | 200 OK | Successful GET, PUT, PATCH, DELETE |
| Success | 201 Created | Successful POST (resource created) |
| Success | 204 No Content | Successful DELETE (no body) |
| Client Error | 400 Bad Request | Malformed request, validation failure |
| Client Error | 401 Unauthorized | Missing or invalid authentication |
| Client Error | 403 Forbidden | Authenticated but not authorized |
| Client Error | 404 Not Found | Resource does not exist |
| Client Error | 409 Conflict | Resource state conflict (duplicate) |
| Client Error | 422 Unprocessable | Valid syntax but semantic error |
| Client Error | 429 Too Many | Rate limit exceeded |
| Server Error | 500 Internal | Unexpected server error |
| Server Error | 503 Service Unavailable | Maintenance or overload |
Error Response Format
json{ "error": { "code": "VALIDATION_ERROR", "message": "Input validation failed", "details": [ {"field": "email", "message": "Must be a valid email address"}, {"field": "age", "message": "Must be between 0 and 150"} ], "request_id": "req_abc123" } }
Rules:
- Never expose stack traces or internal details in production
- Always include request_id for traceability
- Use consistent error codes (ENUM, not free text)
- Login failures: "Invalid email or password" (never reveal which)
Pagination Pattern
json{ "data": [...], "pagination": { "page": 1, "limit": 20, "total": 150, "total_pages": 8, "has_next": true, "has_prev": false } }
For cursor-based (large datasets):
json{ "data": [...], "cursor": { "next": "eyJpZCI6MTAwfQ==", "has_more": true } }
Input Validation Checklist
| Validation | Method | Tool |
|---|---|---|
| Type validation | Schema validation | Zod, Joi, pydantic, Go validator |
| Length limits | Min/max constraints | Schema min/max |
| Pattern matching | Regex | Email, URL, phone patterns |
| Range validation | Number/date bounds | min/max values |
| Enumeration | Allowed values | enum types |
| SQL Injection | Parameterized queries | ORM (Prisma, GORM, SQLAlchemy) |
| XSS | HTML escaping | Template engines, DOMPurify |
| Path Traversal | Path normalization | filepath.Clean + whitelist |
Rate Limiting Strategy
| Target | Limit | Key |
|---|---|---|
| Auth endpoints | 5 req/min | IP |
| General API | 100 req/min | User token |
| File upload | 10 req/hour | User token |
| Public API | 30 req/min | IP |
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).
API Versioning Strategy
| Strategy | Use Case | Example |
|---|---|---|
| URL prefix | Most APIs | /api/v1/users |
| Header | Internal APIs | Accept: application/vnd.api+json; version=2 |
| Query param | Simple APIs | /users?version=2 |
Breaking changes that require version bump:
- Removing or renaming fields
- Changing field types
- Removing endpoints
- Changing authentication methods
Non-breaking changes (no version bump needed):
- Adding new optional fields
- Adding new endpoints
- Adding new query parameters
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "REST naming conventions are just aesthetics" | Consistent resource naming is how clients discover and predict endpoints. Inconsistency multiplies documentation burden. |
| "GraphQL solves over-fetching, so I do not need to design response shapes" | GraphQL shifts complexity to the resolver layer. Poorly designed schemas create N+1 queries and authorization gaps. |
| "Error codes are internal details, clients just need the message" | Clients need machine-readable error codes for programmatic handling. Messages are for humans, codes are for code. |
| "PATCH and PUT are interchangeable" | PATCH applies partial updates; PUT replaces the entire resource. Using them incorrectly breaks idempotency expectations. |
| "I will version the API when it becomes necessary" | Versioning after breaking changes forces emergency migrations. Plan versioning from the first release. |
Hyrum's Law: Every observable API behavior will eventually be depended on by clients. Undocumented response fields, error formats, and timing characteristics become implicit contracts.
Red Flags
- API returns different error formats across endpoints
- Resource names use verbs instead of nouns (e.g., /getUser instead of /users/:id)
- No pagination on list endpoints that can return unbounded results
- Breaking change deployed without API version bump
- GraphQL schema allows unbounded depth or circular queries without limits
Verification
- All endpoints follow consistent naming convention (nouns, plurals, nested resources)
- Error responses use a standard format with machine-readable error code
- List endpoints implement pagination with documented limits
- API versioning strategy present and enforced (URL path, header, or query param)
- Breaking vs non-breaking change classification documented for recent changes
- Input validation returns 400 with specific field-level error details
