How to design bulk operations in REST

· Category: API & REST

Short answer

Bulk operations reduce network overhead and improve throughput by processing multiple resources in a single API call.

Steps

  1. Accept an array of operations or resources in the request body.
  2. Validate all items before executing any to support atomic or best-effort semantics.
  3. Process items in parallel when possible to minimize latency.
  4. Return a detailed response listing success and failure per item with error codes.
  5. Enforce a maximum batch size to prevent resource exhaustion.

Tips

  • Provide an async mode for very large batches that exceed synchronous time limits.
  • Use JSON Patch or a custom action format for heterogeneous bulk updates.
  • Return 207 Multi-Status when individual items have mixed outcomes.
  • Document retry semantics for failed items within a batch.

Common issues

  • Partial failures leaving the system in an inconsistent state.
  • Payloads too large causing gateway timeouts or memory issues.
  • Lack of transactional support making rollback difficult.
  • Clients unable to correlate response entries with original request items.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.