Bulk requests
A “bulk request” is functionally equivalent to a number of individual calls, but “bulked” for efficiency. Each API might or might not use “bulk requests”.
What are bulk requests used for?
Bulk requests are used for creating, updating, or deleting items. They are not used for GET operations, since that can be achieved in other ways.
How do we “bulk” data?
The principle is this:
- The body of a bulk request contains an array of elements, where each element could have been the body of an individual request.
- A bulk response is an array of elements, with elements in the same order as in the request.
- Each bulk response element is either a result, or an error. The response contains the status code that should have been returned if this request was done as an individual request.
- The status code of the bulk call itself does not reflect the individual items, but rather the bulk call. Hence you could get an OK response from the bulk call, but all individual responses could be errors.
A “bulk” is semantically equivalent to a number of “plain” calls
Sending in a number of requests in a bulk shall produce the same result as sending the same individual calls in in the same sequence. So, for example:
POST .../service/bulk with payload [{id=1001, ...}, {id=1002, ...}, {id=1003, ...}]
should produce the same result as:
POST .../service with payload {id=1001, ...}
POST .../service with payload {id=1002, ...}
POST .../service with payload {id=1003, ...}
(Of course in a multi user environment this cannot be guaranteed, as other calls might be serviced between the operations above.)
URL
The URL for a bulk operation ends in “/bulk”, so for instance the URL for bulk upload of users is POST .../user/v1/users/bulk. Each service decides what methods to support as bulk operations.
Request
The request to a bulk is an array containing objects for all the items. Note that the same method is used for all items in the array, so you cannot mix for instance PUT and PATCH.
Each object of the array should be exactly as the body of a corresponding individual call.
Example:
POST .../service/bulk
[ { id=1001, ... }, { id=1002, ... }, { id=1003, ... } ]
Response
The response to a bulk call is an array consisting of responses for the items in the request.
The response returns status code 200, and the Content-Type header field is application/json. (Note that the status code for the call is for the bulk call, NOT for any of its items! The status codes for each individual item that would have been if they were sent individually is part of the response data.)
The bulk response is a single JSON array.
Bulk response: Array
Each item in this array is a Bulk item response object.
Bulk item response: Object
| Field name | Type | Required | Description |
|---|---|---|---|
|
Status |
Number |
Yes |
The HTTP status code ([RFC7231, Section 6]) for the item.
The client can inspect this to see if the operation was successful (2xx) or not (4xx or 5xx). |
|
headers |
Array of Array of Strings |
|
Headers for the item. This could for instance include Content-type for the item.
Each sub-Array contains two strings: a key and a value.
|
|
body |
JSON object |
|
The body for the item.
|
NOTE: “… for the item” above should be interpreted as “… by the service if the call had been an individual call for this item”.
The value for the body field should be exactly as the body of an individual call.
Example of response payload:
[
{
"status": 200,
"body": {
"id": "1001",
"field": "yup",
...
}
},
{
"status": 401,
"headers": [ [ "Content-type", "application/problem+json" ] ],
"body": {
"error": {
"id": "123e4567-e89b-12d3-a456-426614174001",
"code": "not-allowed",
"message": "Your credentials are not enough",
...
}
}
},
{
"status": 204
}
]
Note that the headers value is an array of arrays.