Make batch requests with the REST APIs
This article describes how you can batch queries and operations against the REST/OData API of Microsoft SharePoint Online (and on-premises SharePoint 2016 and later) and the Files and folders subset of the Office 365 REST APIs. With this technique, you can improve the performance of your add-in by combining many operations into a single request to the server and a single response back.
Executive summary of the $batch option
SharePoint Online (and on-premises SharePoint 2016 and later) and the Office 365 APIs implement the OData $batch query option, so you can rely on the official documentation for details about how to use it. (Another option is to see Andrew Connell's blog posts on the subject beginning at Part 1 - SharePoint REST API Batching.)
The following is a reminder of the major points:
- The request URL consists of the root service URL and the
$batchoption; for example,https://fabrikam.sharepoint.com/_api/$batchorhttps://fabrikam.office365.com/api/v1.0/me/$batch. - The HTTP request body is MIME type multipart/mixed.
- The body of the request is divided into parts that are separated from each other by a boundary string that is specified in the header of the request.
- Each part of the body has its own HTTP verb and REST URL, and its own internal body when applicable.
- A part can be a read operation (or function invocation), or a ChangeSet of one or more write operations (or function invocations). A ChangeSet is itself a MIME type multipart/mixed with subparts that contain insert, update, or delete operations.
- The request URL and the URLs inside the body must target the same site. All URLs are case-sensitive.
Important
SharePoint and Office 365 APIs aren't transactional and don't support "all or nothing" functionality for ChangeSets that have more than one operation within them. If any of the child operations fails, the others still complete and aren't rolled back.
Code samples
Samples of code that uses the $batch query option against the SharePoint REST/OData APIs:
- C#: OfficeDev/Core.ODataBatch
- JavaScript: andrewconnell/sp-o365-rest
Example requests and responses
The following is an example of a raw HTTP request that batches two GET operations that retrieve the titles of all the items in two different lists.
POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Host: fabrikam.sharepoint.com
Content-Length: 527
Expect: 100-continue
--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary
GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('Composed%20Looks')/items?$select=Title HTTP/1.1
--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary
GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('User%20Information%20List')/items?$select=Title HTTP/1.1
--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1--
The following is an example of the body of a raw HTTP request that batches a DELETE of a list and a GET of the SharePoint list-of-lists.
POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Host: fabrikam.sharepoint.com
Content-Length: 647
Expect: 100-continue
--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: multipart/mixed; boundary=changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d
--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d
Content-Type: application/http
Content-Transfer-Encoding: binary
DELETE https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('OldList') HTTP/1.1
If-Match: "1"
--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d--
--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: application/http
Content-Transfer-Encoding: binary
GET https://fabrikam.sharepoint.com/_api/Web/lists HTTP/1.1
--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e--
Caution
Batch requests can reduce the number of round-trip requests to the SharePoint REST API. However, uploading multiple files in a single batch is not supported.
OData libraries
OData libraries support OData batching for many languages. Following are two examples. For a more complete list, see OData Libraries.