# API Design

> Design clear, consistent, evolvable REST and GraphQL APIs.

## When to Use
- Designing new endpoints
- Reviewing API architecture
- "Design an API for X"

## Principles
1. **Resources are nouns, actions are verbs** — GET /users, POST /users, not GET /getUsers
2. **Use plural nouns** — /users/123 not /user/123
3. **Nest for relationships** — /users/123/orders not /orders?user_id=123
4. **Version from day one** — /api/v1/ even if you think you won't need it
5. **Return consistent shapes** — every endpoint returns {data, meta, errors}
6. **Use HTTP status codes correctly** — 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
7. **Paginate everything** — limit + offset or cursor-based from the start
8. **Idempotent where possible** — PUT and DELETE should be safe to retry

## Design Checklist
- [ ] Every endpoint has a clear resource and action
- [ ] Error responses include actionable messages
- [ ] Auth is consistent across all endpoints
- [ ] Rate limiting is specified
- [ ] Pagination is present on all list endpoints
- [ ] Response shapes are consistent
- [ ] Breaking changes are versioned

## Common Mistakes
- Designing around implementation instead of consumer needs
- Returning different shapes for the same resource type
- No pagination on list endpoints (works fine with 10 records, dies at 10,000)
- Leaking internal IDs or implementation details in responses
