Combine multiple requests in one HTTP call using JSON batching
JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. For example, a client might want to compose a view of unrelated data such as:
- An image stored in OneDrive
- A list of Planner tasks
- The calendar for a group
Combining these three individual requests into a single batch request can save the application significant network latency.
First JSON batch request
First you construct the JSON batch request for the previous example. In this scenario, the individual requests are not interdependent in any way and therefore can be placed into the batch request in any order.
POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me/drive/root:/{file}:/content"
},
{
"id": "2",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "3",
"method": "GET",
"url": "/groups/{id}/events"
},
{
"id": "4",
"url": "/me",
"method": "PATCH",
"body": {
"city" : "Redmond"
},
"headers": {
"Content-Type": "application/json"
}
}
]
}
Responses to the batched requests might appear in a different order. The id
property can be used to correlate individual requests and responses.
200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"status": 302,
"headers": {
"location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
}
},
{
"id": "3",
"status": 401,
"body": {
"error": {
"code": "Forbidden",
"message": "..."
}
}
},
{
"id": "2",
"status": 200,
"body": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
"value": []
}
},
{
"id": "4",
"status": 204,
"body": null
}
]
}
Request format
Batch requests are always sent using POST
to the /$batch
endpoint.
A JSON batch request body consists of a single JSON object with one required property: requests
. The requests
property is an array of individual requests. For each individual request, the id
, method
, and url
properties are required.
The id
property functions primarily as a correlation value to associate individual responses with requests. This allows the server to process requests in the batch in the most efficient order.
The method
and url
properties are exactly what you would see at the start of any given HTTP request. The method is the HTTP method, and the URL is the resource URL the individual request would typically be sent to.
Individual requests can optionally also contain a headers
property and a body
property. Both of these properties are typically JSON objects, as shown in the previous example. In some cases, the body
might be a base64 URL-encoded value rather than a JSON object - for example, when the body is an image. When a body
is included with the request, the headers
object must contain a value for Content-Type
.
Response format
The response format for JSON batch requests is similar to the request format. The following are the key differences:
- The property in the main JSON object is named
responses
as opposed torequests
. - Individual responses might appear in a different order than the requests.
- Rather than
method
andurl
, individual responses have astatus
property. The value ofstatus
is a number that represents the HTTP status code.
The status code on a batch response is typically 200
or 400
. If the batch request itself is malformed, the status code is 400
. If the batch request is parseable, the status code is 200
. A 200
status code on the batch response does not indicate that the individual requests inside the batch succeeded. This is why each individual response in the responses
property has a status code.
In addition to the responses
property, there might be a nextLink
property in the batch response. This allows Microsoft Graph to return a batch response as soon as any of the individual requests has completed. To ensure that all individual responses have been received, continue to follow the nextLink
as long as it exists.
Sequencing requests with the dependsOn property
Individual requests can be executed in a specified order by using the dependsOn
property. This property is an array of strings that reference the id
of a different individual request. For this reason, the values for id
must be unique. For example, in the following request, the client is specifying that requests 1 and 3 should be run first, then request 2, then request 4.
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "..."
},
{
"id": "2",
"dependsOn": [ "1" ],
"method": "GET",
"url": "..."
},
{
"id": "3",
"method": "GET",
"url": "..."
},
{
"id": "4",
"dependsOn": [ "2" ],
"method": "GET",
"url": "..."
}
]
}
If an individual request fails, any request that depends on that request fails with status code 424
(Failed Dependency).
Bypassing URL length limitations with batching
An additional use case for JSON batching is to bypass URL length limitations. In cases where the filter clause is complex, the URL length might surpass limitations built into browsers or other HTTP clients. You can use JSON batching as a workaround for running these requests because the lengthy URL simply becomes part of the request payload.
Known issues
For a list of current limitations related to batching, see known issues.
See also
For more information about the JSON batch request/response format, see the OData JSON Format Version 4.01 specification, section Batch Requests and Responses.