API design

Reduces network round-trips and server overhead by bundling multiple operations into one request envelope.

API clients: fetching multiple independent resources from the same service in one round-trip; Mobile apps: minimizing battery and data usage from many small calls; Microservices: aggregating fan-out calls to reduce inter-service latency

REST APIs, GraphQL, gRPC, Google APIs, Facebook Marketing API, AWS SDK batch operations, HTTP/2 multiplexing

collect operations → wrap into single envelope → POST to batch endpoint → parse individual sub-responses

• batch endpoint
• multipart/mixed
• sub-response
• partial failure
• idempotency key
• rate limiting
• batch size limit

• Individual sequential requests: simpler but higher latency
• GraphQL single query: more flexible but requires GraphQL infrastructure
• HTTP/2 multiplexing: lower-level alternative at the protocol layer

Assuming atomicity: treating batch as all-or-nothing when most APIs return per-operation statuses; Ignoring partial failure handling: not checking individual sub-response status codes; Exceeding batch size limits: sending too many operations in one envelope and getting a 400; Mixing read and write operations without ordering guarantees; Not setting per-request idempotency keys, causing duplicate side effects on retry

Multiplexing: combines streams over one connection but at protocol level; Bulk operations: server-side batch processing of queued items; Pipeline: sequential without waiting for individual responses

Coming from GraphQL: may assume all batched queries share one response shape — REST batch endpoints return heterogeneous sub-responses keyed by ID. Coming from SQL: may assume transactional atomicity — most batch APIs are not transactional and partial failures are normal.

• bulk operation
• pipeline
• multiplexing
• fan-out
• partial failure handling
• idempotency key

When NOT to use: when operations have strict ordering dependencies, when individual responses are needed before proceeding, or when payload size exceeds server limits. Performance: reduces N round-trips to 1, but increases single-request payload size and server processing time. Boundary conditions: most APIs cap batch size (e.g., 50–1000 operations); partial failures are common and must be handled per sub-response.

Cuts client-side latency dramatically for fan-out patterns, reduces server connection pool pressure, and lowers per-request TLS/auth overhead — but shifts complexity to partial-failure handling and idempotency design.

Batch request: like sending one envelope containing many letters to the same post office instead of walking there for each one — one trip, many deliveries, but you must check each reply individually for problems.

Async batch processing with webhooks or polling for long-running operations