Acting on many records at once.
WHY THEY ARE NEEDED
One request per record is slow and consumes rate limits.
WHAT A BULK ENDPOINT ACCEPTS
A list of operations or records.
WHAT TO DECIDE
Whether it is all-or-nothing, or partial.
WHAT ALL-OR-NOTHING PROVIDES
Simple reasoning.
WHAT IT COSTS
One bad record rejecting the whole batch.
WHAT PARTIAL SUCCESS PROVIDES
Progress despite bad records.
WHAT IT REQUIRES
A per-item result in the response.
WHAT THAT RESULT MUST CONTAIN
The item's identifier or position Whether it succeeded The error, if not
WHAT STATUS CODE TO RETURN
One indicating multiple outcomes, with detail in the body.
WHAT TO NEVER DO
Return success when some items failed.
WHAT TO LIMIT
The number of items per request.
WHY
An unbounded batch is an availability risk.
WHAT TO DO FOR VERY LARGE VOLUMES
An asynchronous job, with a status endpoint.
WHAT TO PROVIDE THEN
Progress A report of failures The ability to retry only the failures
WHAT TO ENSURE
That retrying the batch does not duplicate the successes.
HOW
Idempotency keys per item.
