Agent Wranglers

API-91Recommended

Return a result for each item in a batch

Give each batch endpoint a written item limit, and say whether it is all or nothing. Return one result per item, in request order, with its own status and error.

By Agent Wranglers. Updated .

How to do it

A batch saves round trips when a client creates or changes many records. Refuse a batch over the limit with 422 that names the limit, before doing any work. Google's AIP-233 makes a synchronous batch atomic and lets an asynchronous one report failures per item. An all-or-nothing batch runs in one transaction and fails whole, naming the first bad item. A batch that allows partial success answers 200 with a results list. Each entry holds the item's index, a status code and either the resource or problem details. Never answer a bare 200 when some items failed. Accept an idempotency key for the whole batch, so a retry creates nothing twice. A batch that takes longer than one request runs as a long job.

Examples

JSON example

{
  "results": [
    { "index": 0, "status": 201, "product": { "id": "prd_81", "sku": "MUG-RED" } },
    { "index": 1, "status": 422, "error": { "type": "https://example.com/problems/invalid-field", "title": "Price must be positive", "field": "price" } },
    { "index": 2, "status": 201, "product": { "id": "prd_82", "sku": "MUG-BLUE" } }
  ]
}

How to check

Send a batch of three items where the second is invalid. An all-or-nothing endpoint creates none and names index 1. A partial endpoint creates two and marks index 1 with 422. A batch one item over the limit gets 422 and creates nothing.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/api-design/resources-and-methods/batch-results">Agent Wranglers API design playbook</a>. In code you write, add a comment next to it with the same link.