How do you design a REST API for bulk or batch operations?
Learn how to design REST APIs for bulk and batch operations with 207 Multi-Status, per-item results, atomicity choices, and size limits.
Expected Interview Answer
Design a bulk REST endpoint that accepts an array of items in one request, processes them together, and returns a per-item result list so callers know exactly which entries succeeded and which failed.
Expose a dedicated collection route such as POST /orders/batch that takes a JSON array or an envelope with an operations list. Decide between all-or-nothing (transactional) and partial-success semantics, and reflect the choice in the status code and body. For partial success, return 207 Multi-Status with a result element per input item carrying its own status, id, and error. Cap the batch size, validate up front, and keep each item's outcome independently addressable.
- Fewer round trips and lower latency
- Reduced connection and header overhead
- Per-item success and failure reporting
- Easier atomic or transactional grouping
- Better throughput for high-volume writes
AI Mentor Explanation
A bulk endpoint is like an umpire signalling the outcome of a full over at once instead of walking off after every single ball. Six deliveries are handled in one trip, but the scorebook still records each ball separately — a wide, a dot, a boundary — so the batch is efficient yet every delivery keeps its own individual result and nothing is lost in the grouping.
Step-by-Step Explanation
Step 1
Model the batch payload
Accept a JSON array or an envelope like { operations: [...] } with a client-supplied reference per item so results can be matched back.
Step 2
Choose atomicity semantics
Decide all-or-nothing (wrap in a transaction and roll back on any failure) versus partial success, and document it explicitly.
Step 3
Validate and bound the batch
Reject oversized batches with 413 or 400, validate each item up front, and enforce a documented max size to protect the server.
Step 4
Process and collect results
Run items independently for partial-success mode, capturing each item's status, id, and any error message.
Step 5
Return a per-item response
Use 207 Multi-Status for mixed outcomes with a results array; use 200/201 for full success and 4xx when the whole request is invalid.
What Interviewer Expects
- Awareness of round-trip and overhead reduction
- Clear atomic vs partial-success trade-off
- Use of 207 Multi-Status for mixed results
- Per-item result mapping via client references
- Batch-size limits and up-front validation
Common Mistakes
- Returning a single status code that hides per-item failures
- Not bounding batch size, enabling denial-of-service
- Assuming every batch must be fully transactional
- Losing the mapping between input items and results
- Overloading GET with huge query strings instead of POST
Best Answer (HR Friendly)
“A bulk API lets a client send many records in one request instead of hundreds of separate calls, which is much faster. The response reports what happened to each individual record, so the client knows exactly which ones worked and which ones need attention.”
Code Example
POST /v1/orders/batch
Content-Type: application/json
{
"operations": [
{ "ref": "a1", "sku": "BOOK-01", "qty": 2 },
{ "ref": "a2", "sku": "PEN-99", "qty": 5 }
]
}
HTTP/1.1 207 Multi-Status
{
"results": [
{ "ref": "a1", "status": 201, "id": "ord_781" },
{ "ref": "a2", "status": 422, "error": "SKU not found" }
]
}Follow-up Questions
- How would you make a batch write endpoint idempotent?
- When would you choose all-or-nothing over partial success?
- How do you paginate very large batch responses?
- What status code fits a partially successful batch?
- How do you rate-limit clients that send large batches?
MCQ Practice
1. Which status code best signals a mixed success/failure batch result?
207 Multi-Status is designed to carry multiple independent per-item statuses in one response body.
2. What is the main performance benefit of a bulk endpoint?
Sending many items in one request removes the per-request connection and header overhead of many separate calls.
3. Why include a client-supplied reference per batch item?
A per-item reference lets the client correlate each returned result with the exact item it submitted.
Flash Cards
What status code suits a partial-success batch? — 207 Multi-Status, carrying a per-item status array in the body.
Atomic vs partial-success batch? — Atomic rolls back all items on any failure; partial-success commits the ones that succeed and reports the rest.
Why bound batch size? — To protect the server from oversized payloads and denial-of-service, returning 413 or 400 when exceeded.
How do clients match results to inputs? — Include a client-supplied ref per item and echo it in each result element.