SharePoint 2013: CSOM vs. REST ... My Preference and Why

Earlier this week I watched a dialog progress between a few people on a email distribution list that I’m on where they mused about which client-side friendly API they prefer in SharePoint 2013. The two options are the client side object model (CSOM), which also includes the JavaScript implementation that’s more commonly referred to as the JSOM these days, and the REST (aka OData) option. It got me thinking that I had never posted my thoughts although I get this question quite a bit.

I’ll start with quick overview of the two

The CSOM (and the JSOM by extension) is a Microsoft generated collection of libraries that acts as a proxy to the server-side object model. The CSOM is not a complete replacement for the server side object model. The way I look at it is that I can do just about everything I need to do using the CSOM within a specific site collection. In SharePoint 2013 it was greatly improved as it got additions for working with search, BCS, taxonomies, workflows and user profiles to name just a few. The CSOM is available in managed form for .NET and Silverlight clients as well as unmanaged form in JavaScript (aka: the JSOM).

The REST interface on the other hand is mostly brand new in the SharePoint 2013 release. There was a single service in SharePoint 2010 that we could use that enabled read/write to data within a list. The current REST implementation covers a huge area of SharePoint 2013. For those of you keeping score, this is also an OData interface to SharePoint 2013.

REST is something a Roy Fielding wrote back in 2000 that described a way to share data over HTTP. Unfortunately companies created very different implementation of RESTful services so a bunch got together to define an agreed upon protocol called the Open Data Protocol, also known as OData). The OData spec defines the data formats returned as well as the specific vocabularies used to interact with OData services. Each vendor then implemented it on their own technology stack. Microsoft did this and called their OData product WCF Data Services (notice the URL is actually odata.aspx on MSDN). SharePoint 2013’s REST interface is built using WCF Data Services 5.0 which implements the OData v3.0 specification. Unfortunately the SharePoint 2013 implementation does not include everything the spec states, but it’s pretty close.

By the way, if you’re looking for some great training on this subject, check out Rob Windsor’s epic 6.5 hour course at Pluralsight that does a great job of demonstrating both: SharePoint 2013 Development: Client Object Model and REST API.

My Thoughts

For the email discussion that I witnessed, most people were favoring the CSOM over the REST API in SharePoint 2013 for a few reasons. Most boiled down to the fact that when developing with REST, your custom code tends to be more chatty with the server than CSOM. For instance, if I wanted to create a list with a few custom fields, I could do that in one round trip to the server if using CSOM, but with REST it would be 1 call for the creation of the list and (n) calls for each field I want to create.

Another thing to mention is that when working with the CSOM, the libraries SharePoint provides handle all the plumbing of the HTTP request/response for us. However when using REST, you build it up yourself, including the digest values (required for SharePoint’s handing of the replay attack), the type of data you want, the HTTP method, etc. So there is a bit more work to working with REST.

Now, keep in mind that before I pitch my preference in the rest of this post, I strongly believe there is no right or wrong answer. I guess there is one wrong answer: people who say one is better than the other one. Fact is just like everything else in SharePoint, we’ve got multiple ways to do the same thing and we can choose what we like best for our situation.

However with that being said, for me I strongly prefer REST over the CSOM for numerous reasons. The only exception to this is when there is something in the CSOM that I can’t do in REST. Two big cases come to mind here (but there are others): the REST API doesn’t have support for working with managed metadata taxonomies and I also can’t interact with workflows via REST. The CSOM has coverage for both of these things, including a very robust Workflow Services CSOM API (sadly it’s poorly documented… in fact, sadly, its full of inaccuracies).

So… why do I prefer REST over CSOM? Let me enumerate a few things:

Data Access: with CSOM, I have to write CAML queries (nasty) whereas with the REST API I use OData vocabularies and the documentation is quite good
With the REST API, I can use any of the open source & community libraries available, and there are a ton including the following. With CSOM, it’s my code + CSOM… zero to very few utility libraries out there.
Client side (my favorites):
- jQuery
- Knockout plugin mapping to my models
- Linq.js
- Data.js
Server Side:
JSON.NET
.NET FX 4.0’s JavaScript serializer
With the REST API, there is a lot more documentation out there, and stuff not supplied by MSFT, so when I need help, it’s easy to find an answer. For CSOM, it’s 100% SharePoint and even what’s on MSDN has some gaps for 2013 (nature of a new release)… one small example: Workflow Services CSOM API (contains inaccuracies and a lot of gaps as last published prior to B2 public release ~12mo ago).
With the REST API, I can easily test queries in the browser & using Fiddler making me more productive. With CSOM, I must write something and run it in SharePoint / console app.

There’s one point (I touched on it previously in this post) that keeps being made by the CSOM zealots over REST that I find someone ironic: REST is chattier than CSOM.

This is an academic argument in my point of view. Yes, because we lack batching support in SharePoint REST, you bet it is but that is something the SharePoint team could implement as the technology they rely on (WCF Data Services 5.0) already supports it (Batching Operations). But the current state is we don’t have it. Still it’s an interesting argument to make. Consider this counter point: if you’re writing a web app, have you looked at Fiddler when you make your single page request? Notice all YOUR CSS, JavaScript & images being requested in a separate HTTP request? We all [likely] know that you can “batch” these by combining CSS & JavaScript and merging images using sprites, but do we do it? From what I see, the vast majority doesn’t. So (and I’m admittedly painting with a big brush) you’ve already shot down the “I won’t use it because it’s chatty” because your app is already chatty.

It all Boils Down To

I for one prefer the REST API over CSOM because I find I’m much more productive with the REST API than when I use CSOM and have to deal with client context’s, .Load(), .LoadQuery(), even though I have to build the HTTP request myself manually (I use a JavaScript utility object I wrote for this). Of course, your mileage may vary and you may prefer the CSOM. By all means, no problem there! It’s just my blog, my thoughts and my opinion :)