Implementing Batch Operations
1. Creating Multiple Resources
Example: Batch Create
POST /users/batch
Content-Type: application/json
{
"items": [
{"name": "Alice", "email": "alice@x.com"},
{"name": "Bob", "email": "bob@x.com"}
]
}2. Updating Multiple Resources
| Pattern | Example |
|---|---|
| Bulk PATCH | PATCH /users/batch with id+changes per item |
| Filter-based update | POST /users/bulk-update?status=inactive |
3. Deleting Multiple Resources
| Pattern | Example |
|---|---|
| POST with IDs | POST /users/batch-delete body: {"ids":[1,2,3]} |
| DELETE with body | DELETE /users body: {"ids":[...]} (some proxies strip) |
| Query filter | DELETE /users?status=spam (dangerous; require confirmation) |
4. Using Batch Endpoints
| Convention | URI |
|---|---|
| Sub-action on collection | POST /users/batch |
| Heterogeneous batch | POST /batch with method+url+body per op |
| HTTP multipart | Each part is one HTTP request (Google APIs style) |
5. Implementing Partial Success Handling
| Status | When |
|---|---|
| 200 OK | All succeed; per-item results in body |
| 207 Multi-Status | Mixed success/failure (WebDAV) |
| 422 | If atomic batch fails any item |
6. Returning Batch Results
Example: Batch Result with Per-Item Status
{
"results": [
{"index": 0, "status": 201, "id": 100, "data": {...}},
{"index": 1, "status": 422, "error": {"code": "DUPLICATE_EMAIL"}},
{"index": 2, "status": 201, "id": 101, "data": {...}}
],
"summary": {"total": 3, "succeeded": 2, "failed": 1}
}7. Implementing Transaction Support
| Mode | Behavior |
|---|---|
| Atomic (all-or-nothing) | Single DB transaction; one failure → rollback all |
| Best-effort | Each item independent; partial success possible |
| Header-controlled | Prefer: handling=strict vs handling=lenient |
8. Setting Batch Size Limits
| Limit | Typical |
|---|---|
| Items per batch | 100-1000 |
| Total payload | 10 MB |
| Timeout | 30s sync, async beyond |
| Over limit | 413 Payload Too Large or 400 |
9. Handling Batch Validation Errors
| Mode | Validation Strategy |
|---|---|
| Strict | Validate all upfront; reject batch if any invalid |
| Lenient | Process each; report per-item errors |
| Best practice | Always validate request envelope (max items) up front |
10. Documenting Batch Operation Behavior
| Documentation Element | Content |
|---|---|
| Atomicity | All-or-nothing vs partial |
| Limits | Max items, max size |
| Result format | Per-item status structure |
| Idempotency | Behavior on retry |