Implementing API Design Patterns
1. Implementing RESTful Resource Modeling
| Pattern | Example |
|---|---|
| Collection | GET /orders, POST /orders |
| Item | GET /orders/42, PUT, DELETE |
| Sub-resource | GET /orders/42/items |
| Action | POST /orders/42/cancel (when not CRUD) |
| Plural nouns | Use plural; never verbs in path |
2. Implementing Pagination
| Style | Pros | Cons |
|---|---|---|
| Offset/Limit | Simple, jump to page | Slow at deep pages; inconsistent with inserts |
| Cursor (keyset) | Fast, consistent | No random page access |
| Page token (opaque) | Hides impl; resilient | Server-side state encoding |
| Time-based | Streams (since=...) | Tie-breaker needed |
Example: Cursor pagination response
{
"data": [ /* ...items... */ ],
"next_cursor": "eyJpZCI6MTIzfQ==",
"has_more": true
}3. Implementing Filtering and Sorting
| Convention | Example |
|---|---|
| Equality filter | ?status=active |
| Range | ?created_after=2026-01-01 |
| Sort | ?sort=-created_at,name (- = desc) |
| Field selection | ?fields=id,name |
| RSQL/JSON-API | Standard query languages |
4. Implementing API Versioning
| Strategy | Example | Notes |
|---|---|---|
| URL path | /v2/orders | Most visible; simple |
| Header | Accept: application/vnd.api+json;v=2 | Cleaner URLs |
| Query param | ?api-version=2 | Easy to test |
| Date-based | 2026-01-01 (Stripe) | Per-customer pinning |
5. Implementing Rate Limiting Headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Window quota |
X-RateLimit-Remaining | Remaining in window |
X-RateLimit-Reset | Unix ts of reset |
Retry-After | Seconds to wait (on 429) |
RateLimit-* (RFC 9239) | Standardized variants |
6. Implementing HATEOAS
Example: HAL-style response
{
"id": 42,
"status": "pending",
"_links": {
"self": { "href": "/orders/42" },
"cancel": { "href": "/orders/42/cancel", "method": "POST" },
"items": { "href": "/orders/42/items" }
}
}| Format | Notes |
|---|---|
| HAL | _links object |
| JSON:API | Top-level links + relationships |
| Siren | Includes actions with method/fields |
7. Implementing Idempotency Keys in APIs
| Aspect | Detail |
|---|---|
| Header | Idempotency-Key: <uuid> |
| Scope | Per endpoint + per API key |
| Replay | Same key returns identical response |
| TTL | 24h (Stripe) to 7 days |
8. Implementing Bulk Operations
| Pattern | Detail |
|---|---|
| Batch endpoint | POST /orders/batch with array |
| Per-item status | 207 Multi-Status with sub-codes |
| All-or-nothing | Transaction-like; reject all on any error |
| Chunking | Server limits batch size (100-1000) |
9. Implementing Long-Running Operations
Async LRO Pattern
- Client POSTs request → server returns
202 Accepted+ operation id - Server sets
Location: /operations/{id} - Client polls
GET /operations/{id}for status - Or server fires webhook on completion
- Final response includes result or error
10. Implementing API Error Handling and Status Codes
| Code | Meaning |
|---|---|
| 200/201/204 | Success / Created / No Content |
| 400 | Validation / malformed |
| 401 / 403 | Unauthenticated / Forbidden |
| 404 / 409 | Not Found / Conflict |
| 422 | Unprocessable entity (semantic) |
| 429 | Rate limited |
| 500 / 502 / 503 / 504 | Server error / Bad gateway / Unavailable / Timeout |
| RFC 7807 | application/problem+json error format |