CHEAT SHEET #04Quick Reference Architecture•5 min read
REST API Design, Idempotency & Protocol Cheat Sheet
Production engineering guide for designing enterprise RESTful APIs, idempotency keys, pagination protocols, and resilient error handling.
FreeCheat SheetDatabasesAPIs
Production engineering guide for designing enterprise RESTful APIs, idempotency keys, pagination protocols, and resilient error handling.
1. The 6 Architectural Constraints of REST
Interactive Architecture DiagramSynthesizing vector architecture diagram...
- Client-Server Separation: Separation of UI concerns from data storage concerns.
- Statelessness: Every request contains all necessary session tokens and parameters.
- Cacheability: Responses explicitly declare whether they can be cached via
Cache-ControlandETag. - Uniform Interface: Identification of resources via URIs; manipulation via standard representations.
- Layered System: Client cannot determine whether it is connected directly to end server or an intermediary.
- Code on Demand (Optional): Servers can temporarily extend client functionality (e.g., JavaScript).
2. HTTP Methods & Idempotency Matrix
| HTTP Method | Safe? (No state change) | Idempotent? (N calls = 1 call) | Cacheable? | Typical Use Case |
|---|---|---|---|---|
| GET | ✅ Yes | ✅ Yes | ✅ Yes | Retrieve resource representations |
| HEAD | ✅ Yes | ✅ Yes | ✅ Yes | Retrieve response headers only (size, ETag) |
| POST | ❌ No | ❌ No | ⚠️ Conditional | Create a new subordinate resource |
| PUT | ❌ No | ✅ Yes | ❌ No | Complete replacement of existing resource |
| PATCH | ❌ No | ❌ No (Can be made so) | ❌ No | Partial update / delta modification of resource |
| DELETE | ❌ No | ✅ Yes | ❌ No | Remove target resource |
| OPTIONS | ✅ Yes | ✅ Yes | ❌ No | CORS preflight & server capabilities |
3. HTTP Status Codes Quick Reference
Interactive Architecture DiagramSynthesizing vector architecture diagram...
4. Pagination Design: Offset vs. Keyset (Cursor)
| Pagination Dimension | Offset-Based (?page=5&limit=20) | Cursor / Keyset-Based (?cursor=eyJpZCI6MTB9) |
|---|---|---|
| SQL Implementation | LIMIT 20 OFFSET 80 | WHERE id > :last_id ORDER BY id ASC LIMIT 20 |
| Performance at Scale | ❌ Severe degradation: DB scans and discards all skipped rows. | ✅ O(1) index seek regardless of whether row is 10th or 10,000,000th. |
| Stability (Data Drift) | ❌ Missed rows or duplicates if records inserted while paginating. | ✅ Deterministic: Cursor points to exact immutable position. |
| Random Page Navigation | ✅ Jump directly to Page 42. | ❌ Only sequential Next / Previous scrolling. |
| Recommendation | Admin dashboards with small total counts (< 1,000 items). | Mobile feeds, infinite scroll, high-scale public APIs. |
5. Idempotency Key Implementation Pattern
When clients issue unsafe requests like POST /v1/payments, network timeouts can cause duplicate billing if retried without protection.
Interactive Architecture DiagramSynthesizing vector architecture diagram...
6. Rate Limiting Headers Specification
Always return standard rate limit context in every HTTP response:
httpHTTP/1.1 200 OK X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 985 X-RateLimit-Reset: 1772841600 Retry-After: 60