Bulk and Batch APIs

Overview

A bulk or batch API processes many items per request. It reduces network round trips and fixed per-request costs such as authentication, TLS and rate limit accounting, and lets the server apply set-based optimisations.

How it works

The client sends an array; the server validates, processes and reports per-item results.

POST /contacts:batchCreate
{ "items": [ {"ref":"a1","email":"x@e.com"}, {"ref":"a2","email":"bad"} ] }

207 Multi-Status
{ "results": [
    {"ref":"a1","status":201,"id":"c9"},
    {"ref":"a2","status":422,"error":"invalid email"} ] }

The ref field is a client-chosen id that correlates results and makes retries idempotent. Cap items per call, for instance 100, and total body size. For very large imports, return 202 Accepted with a job URL; the client polls the job for progress and a result file. For reads, accept a list of ids on a batch get endpoint.

Pitfalls

• Ambiguous atomicity. State clearly whether a batch is transactional; most large batches should not be.
• Returning 200 for a batch that partly failed without per-item detail.
• No size or time limits, allowing one request to monopolise a worker.
• Missing idempotency, so a retried timeout duplicates the successful items.
• Rate limiting by request count only; account by item count as well.

Key takeaways

• Bound batch size and report outcome per item.
• Use client refs and idempotency keys for safe retries.
• Go asynchronous with job resources for large volumes.
• Document atomicity semantics explicitly.
• Measure it in production: track latency, error rates and volume for this pattern, and review the numbers regularly so that limits and timeouts stay matched to real traffic.