# API Design Quick Reference

## REST

| Verb | Action | Example |
|------|--------|---------|
| GET | Read | GET /users/42 |
| POST | Create | POST /users |
| PUT | Replace | PUT /users/42 |
| PATCH | Partial update | PATCH /users/42 |
| DELETE | Remove | DELETE /users/42 |

**Conventions:** Plural nouns, hierarchy in URL, consistent casing

## REST vs GraphQL

| REST | GraphQL |
|------|---------|
| Many endpoints | Single endpoint |
| Fixed responses | Client-specified fields |
| HTTP cache | Custom cache |
| Simpler | More flexible |

## Status Codes

| Code | Meaning |
|------|---------|
| 200 | OK |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Server Error |

## Versioning

- **URL:** `/v1/users` — clear, cacheable
- **Header:** `Accept: application/vnd.api+json;version=2`

## Pagination

- **Offset:** `?offset=20&limit=10` — simple, can drift
- **Cursor:** `?cursor=abc&limit=10` — stable for feeds

## Auth

| Method | Use |
|--------|-----|
| API Key | Server-to-server |
| OAuth 2.0 | Delegated user access |
| JWT | Stateless, `Authorization: Bearer <token>` |

## Error Body

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "details": []
  }
}
```

## Rate Limit Headers

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
Retry-After: 60
```