API Design Rules

When creating or modifying API endpoints, follow these REST conventions:

## URL Structure
- Use nouns, not verbs: /api/users (not /api/getUsers)
- Use plural nouns: /api/posts (not /api/post)
- Nest for relationships: /api/users/:id/posts
- Use kebab-case for multi-word resources: /api/user-profiles
- Max nesting depth: 2 levels

## HTTP Methods
- GET — Read (no side effects, cacheable)
- POST — Create (returns 201 + created resource)
- PUT — Full replace (idempotent)
- PATCH — Partial update (returns updated resource)
- DELETE — Remove (returns 204 no content)

## Response Format
- Always return JSON
- Wrap collections: { data: [], meta: { total, page, limit } }
- Single resources: { data: { ... } }
- Errors: { error: { code: "NOT_FOUND", message: "User not found", details: {} } }
- Use consistent date format: ISO 8601 (2025-01-15T10:30:00Z)

## Status Codes
- 200 OK — Successful read/update
- 201 Created — Successful creation
- 204 No Content — Successful deletion
- 400 Bad Request — Validation error
- 401 Unauthorized — Missing/invalid auth
- 403 Forbidden — Valid auth but insufficient permissions
- 404 Not Found — Resource doesn't exist
- 409 Conflict — Duplicate or state conflict
- 422 Unprocessable Entity — Business logic validation failure
- 429 Too Many Requests — Rate limit exceeded
- 500 Internal Server Error — Unexpected server error