In SharePoint we have two ways to interact with our data from off the server: the client-side object model (CSOM) and the REST API. Everyone has their preference and their reasons why they prefer one over the other. I wrote about my preference of REST over the CSOM in the past. There are some things that CSOM has over REST aside from the few things you can only do with CSOM that aren’t available with the REST API such as interacting with workflows or managed metadata.
There are two more things that always seem to come up when people compare CSOM to REST. One is the fact that when you use the REST API, you have to write a lot more plumbing code as you handle the entire HTTP request. For me I get around that with the popular BreezeJS library which you can read more about in my series that I wrote about here: BreezeJS Makes Client Side SharePoint 2013 REST Development a Breeze!.
However the other point people make is that with the CSOM, you can batch up a bunch of requests rather than sending a ton of HTTP requests over the wire. The SharePoint REST API has not supported this for the longest time so if you had 10 items you wanted to create in a list, you had to issue 10 separate HTTP POST requests. This has been frustrating because the SharePoint REST API shipped claiming OData v3.0 support which you can see from the OData v3.0 protocol docs, supports a $batch operator! Unfortunately SharePoint hasn’t supported it…
Until now…
That’s right folks! As you can see from this UserVoice submission, it’s now live in Office 365! Now you can batch up a bunch of requests in a single HTTP request and cut down on the chatty part of using the REST API! This is a HUGE deal! I’ve been playing with this a bit over the last few days and created a sample SharePoint Hosted App you can grab to see it in action. You can get it from my SharePoint & Office365 REST API Resources repository in GitHub, specifically you want the SpRestBatchSample.
SharePoint REST Batch Sample
This little demo app shows you how to do a few things. It enables you run operations in single request or batch request mode. The app creates a list that will store Formula 1 drivers. Click the add buttons to add drivers (two per team) from the 2013 teams for Ferrari, Mercedes & Red Bull. Click the update button to update the Ferrari and Red Bull teams (two drivers updated total) to their 2014 drivers (as these two teams had turnover between the two seasons). The Get All Teams button issues a request to refresh the list and the Delete All Teams deletes all the drivers from the list. Notice there’s a checkbox at the top for submitting the requests using batches. All the code you care about is in the /Scripts/App.js, I’m using the popular KnockoutJS to simplify the data binding to present the data, jQuery to issue AJAX requests to the REST API and the Q library for better JavaScript promises support.
Let’s compare the difference. Below is a screenshot from a Fiddler trace:
Fiddler trace of SharePoint Batch requests
Sessions 1 - 10 in the trace demonstrate me clicking each of the add buttons in succession. Each button click creates three HTTP requests… two HTTP POSTS to create the driver for the specified team (those are the ones that have a 201 result which is the status code response for a successful POST) followed by a single HTTP GET to get an updated list of the drivers. I then clicked the update button which issued two HTTP POST requests (sessions 13-14) for each item updated in the list, followed by another HTTP GET to get the contents of the list. Then when I click the delete button, it issues a single HTTP DELETE request (sessions 16-21) for each item in the list, followed by another HTTP GET to get the contents of the list (session 22).
However if you check the box for batch requests, notice the difference from sessions 1-22 compared to 24-28. Each of the add button clicks issues the two add HTTP POSTS followed by a HTTP GET to get the contents of the list… three operations wrapped up in a single HTTP GET. Session 27 issues the two updates & the last one (session 28) issues six HTTP DELETE requests and a single HTTP GET… how about that!
Enough of a sales pitch… let’s dive into how this works. In the next post I’ll talk about the details of a batch request and then pick apart some of the aspects… let’s get to it! Jump to the next post: SharePoint REST API: Exploring Batch Requests, Responses and Changesets. In that post I’ll explain a few challenges I’ve run into, specifically with updates & changeset responses.
Where Does this Work?
Today batch support is only available in SharePoint Online in Office 365. What about folks who have SharePoint 2013 on-premises? Here’s another case where Microsoft is building for the cloud first. Right now they haven’t discussed plans when this will be available on-premises… maybe in a future CU or service pack… but for now I wouldn’t expect to see it until the next on-premises version ships which has been slated for the second half of calendar year 2015.