Bulk Operations
You'll learn to
- -Design a batch endpoint that processes multiple items in one request without an all-or-nothing failure model
- -Use 207 Multi-Status to report per-item success/failure within a single batch response
Creating or updating a hundred resources one HTTP request at a time is slow and wasteful when a client genuinely has a hundred items to submit at once - a batch endpoint processes many items in a single round trip, but it introduces a real design question plain CRUD doesn't have: what happens when some items succeed and others fail?
Batch Endpoints
POST /orders/batch
{
"orders": [
{"product_id": 1, "quantity": 2},
{"product_id": 999, "quantity": 1},
{"product_id": 3, "quantity": -5}
]
}Partial Success: 207 Multi-Status
HTTP/1.1 207 Multi-Status
{
"results": [
{"index": 0, "status": 201, "id": 501},
{"index": 1, "status": 404, "error": "product_id 999 does not exist"},
{"index": 2, "status": 422, "error": "quantity must be positive"}
]
}An all-or-nothing model (fail the entire batch if any single item is invalid) is simpler to implement but often the wrong choice for real batch workloads - a client submitting 100 items rarely wants 99 valid items rejected because of one bad one. 207 Multi-Status reports a per-item outcome within one overall response, letting the client see exactly which items succeeded and which failed, and why, without resubmitting the whole batch.
When All-or-Nothing Is Actually Correct
Partial success isn't always right, though - if the batch represents one logical transaction (transferring funds between several accounts as one atomic operation, for instance), partial success would leave the system in an inconsistent intermediate state, and all-or-nothing (with a single clear error identifying what failed) is the correct model instead. The design decision is genuinely use-case-specific: independent items batched for efficiency want partial success; one logical operation split across multiple items wants atomicity.
Always echo back an index or client-supplied identifier per item in a 207 response - without it, a client receiving "item 2 failed" has no reliable way to map that back to which of the items it originally submitted, especially if the batch is large.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design Bulk Operations HQ in the API Design Lab's Production Patterns act.