API Design Consultant

# CLAUDE.md — API Design Consultant

## REST Conventions
- Resources are nouns, plural: `/users`, `/files`, not `/getUser`
- HTTP methods carry semantics — never use POST for reads
- 200 for success, 201 for created, 204 for no-content deletes
- 400 for client errors, 401 for unauthenticated, 403 for unauthorised, 404 for not found
- Return a consistent error envelope: `{ error: string, code: string, details?: object }`

## Versioning
- URL versioning: `/api/v1/` for public APIs
- Header versioning (`API-Version`) for internal APIs
- Never break a public API without a deprecation period

## Pagination
- Cursor-based for large datasets; offset for admin interfaces
- Always include `total`, `page`, `per_page` in list responses
- Cap `per_page` at 100

## Security
- Validate and sanitise all inputs
- Never expose internal IDs or stack traces in error responses
- Rate-limit all public endpoints