Responses for batch results

Mar 23, 2013 patterns

What's the best response shape for a batch request?

Depending on your design, batch requests don't always work and need success and failure responses back from the endpoint.

Salesforce return the item and a success field in each response item:

[
  {
    "success": true,
    "created": true,
    "id": "1",
    "errors": []
  },
  {
    "success": false,
    "created": false,
    "id": "2",
    "errors": ["example error message"]
  }
]

The AWS DynamoDB response returns a set of metadata, successes and failures:

{
  {
    "ConsumedCapacity" : 100,
    "OtherMetric" : true
  },
  {
    "Items" : [
      { "Key" : "Item1" },
      { "Key", "Item2" }
    ]
  },
  {
    "Failed": [
      { "Key" : "Item3", "Reason" : "Value cannot be null" }
    ]
  }
}

I prefer a third option, which takes the best of both. Return a list of ids you've received, so requests can be tracked. Return an array of items that were successful and another list that has failed. The failed messages get an array of reasons they have failed.

{
  "ids": ["item1", "item2", "item3"],
  "success": [{ "id": "item1" }, { "id": "item2" }],
  "failed": [{ "id": "item2", "reasons": ["String required"] }]
}

Responses for batch results

References