What’s New in SharePoint 2013 CSOM and REST APIs

With the new SharePoint App Model in SharePoint 2013, every SharePoint developer will encounter SharePoint 2013 CSOM and REST based APIs while building apps for the corporate or public market place. In past, CSOM and REST based APIs weren’t popular compare to Server Side Object Model for many reasons including limited API support. Unless you were building applications using JavaScript or Silverlight or from remote clients like CRM or other SharePoint farms, many times Server Side Object Model with the full API was a better choice over CSOM or REST based APIs.

With the SharePoint 2013 Apps Model, Microsoft has improved both CSOM and REST based APIs and added much needed support for the Search, User Profiles, Taxonomies, and Publishing Object Model. In addition to additional APIs, both REST and CSOM APIs are available through same endpoint making it almost equivalent APIs.

Recently I had a chance to watch Ted Pattison’s Ignite training video posted on MSDN for the CSOM and REST based API overview in SharePoint 2013. This post contains high level notes and quick overview of what’s new regarding CSOM and REST based support in SP2013 developers should expect and why they should be excited for.

SharePoint 2013 strategy for SharePoint client object model (CSOM) and REST

  • CSOM in SharePoint 2010
    • CSOM was made available through WCF entry point – _vti_bin/client.svc
      • SharePoint 2010 doesn’t support direct access to the client.svc
      • Three programming model – .NET CSOM, Silverlight CSOM, and JavaScript CSOM
      • Calls to the client.svc must go through supported proxy entry points & assemblies e.g. SP.JS for JavaScript CSOM and runtime DLLs in .NET CSOM and Silverlight CSOM, Proxy will forward request to the client.svc in XML format
      • Client.svc sends JSON response/results back to the client which would be formatted into user friendly formatted JavaScript or .NET objects for users to consume
    • Managed CSOM easier to use than from JavaScript
      • JavaScript driven CSOM hard to use and more limited – no compile time checking or IntelliSense
  • CSOM changes in SharePoint 2013
    • Four programming model – .NET CSOM, Silverlight CSOM, JavaScript CSOM, and REST CSOM
    • Most significant improvement in CSOM is client.svc service extended with REST capabilities
      • client.svc now supports direct access from REST clients
      • client.svc accepts HTTP GET, PUT, POST requests
      • Implemented in accordance with OData protocol
      • Evens the field with Non .NET developers to access SharePoint data – Can be called from Non .NET clients through REST based APIs
    • CSOM extended new APIs
      • New APIs for SharePoint Server functionality
      • New API for Windows Phone Applications
    • New CSOM entry point is available in _api, this is mapped to the entry point of client.svc, No need to directly access _api from the .NET CSOM, JavaScript CSOM, or Silverlight CSOM, Just use same proxy & entry points as SP2010 – Runtime DLLs & SP.JS
    • New APIs with SharePoint Server functionality – They are all available in Sever Side .NET CSOM and REST based APIs
      • User Profiles (no need to use User Profiles ASMX for remote calls)
      • Search (no need to use Search.ASMX for remote calls)
      • Taxonomy
      • Feeds
      • Publishing
      • Sharing
      • Workflow
      • E-Discovery
      • IRM
      • Analytics
      • BCS
  • What about ListData.svc?
    • ListData.svc carried over from SharePoint 2010
      • Use REST CSOM when writing JavaScript
      • ListData.svc still available for backward compatibility – for migrated client applications

Programming SharePoint client object model (CSOM) with C# and JavaScript for SharePoint 2013

  • Overview of CSOM Architecture – Same as SP2010 CSOM
  • Changes to the CSOM
    • In SharePoint Foundation
      • No Significant changes to the CSOM apart from the REST support
      • Primary investment is adding REST supports to the existing API
      • For .NET CSOM Reference – Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll
      • For JavaScript CSOM Reference – Load SP.js, ensure sp.js is loaded and initialize CSOM objects
    • In SharePoint Server
      • New APIs have been added with CSOM and REST for duel support
      • Reference – Microsoft.SharePoint.Client.DocumentManagement.dll, Microsoft.SharePoint.Client.Publishing.dll, Microsoft.SharePoint.Client.Taxonomy.dll, Microsoft.SharePoint.Client.UserProfiles.dll, Microsoft.SharePoint.Client.Search.dll etc.

 SharePoint 2013 REST and OData fundamentals

  • Why is REST important?
    • REST has significant Industry Momentum – Much simpler architecture for web services
      • It must run on any platform
      • It has to be able to make HTTP Request
      • It has to be able to authenticate from any platform
    • Simpler and Easier to Use
      • Much easier to use than SOAP based web service – Before REST used by industry, web service technology was based on SOAP, Major limitations of it’s non-flexibility, it was hard to create, consume, and maintain, focused on what goes in the HTTPRequest header and body to request data, data was returned in XML format and must be parsed for the result set
      • Higher productivity when using JavaScript and jQuery
      • Results can be returned in JSON and ATOM format
    • Each query is submitted with a unique URL
      • SOAP was using same URL and request was transmitted in the SOAP header, REST simplified the request process by having separate URL for different queries or operations you want to execute
      • REST Results can be cached by proxy servers because you no longer expect different results & run two different queries using same URL
  • ODATA Primer
    • ODATA is new data access API for HTTP based clients
      • Standardizes data access APIs for CRUD operations e.g. it is similar to the DAO, ADO, ADO.NET APIs which were CRUD in-memory API
    • OData Services are emerging on internet (e.g. Netflix, Dallas, Azure)
  • OData Implementation Details
    • OData maps CRUD operations to HTTP Verbs
      • CRUD operations using HTTP Verbs like GET, PUT, POST, DELETE, MERGE to create, read, delete, update records over the HTTP
      • - Read operations mapped to HTTP GET
      • Insert operations mapped to HTTP POST
      • Update operations mapped to HTTP PUT or HTTP MERGE – Difference between PUT or MERGE is – e.g. if you have 20 columns in SharePoint list and you want to update only 3 columns, PUT will update 3 columns and reset other 17 columns to it’s default value while MERGE will update 3 columns leaving other 17 columns as it is with existing values
      • Delete operations mapped to HTTP DELETE
    • You can query data from the browser and see the results using HTTP GET, You can’t submit query from the browsers for others verbs like POST, PUT, MERGE, or DELETE
    • HTTP Request Methods will be mapped into either
      • Navigator operations (e.g. web.getByTitle) via GET
      • Service operations via a POST, PUT, MERGE, or DELETE
  • OData URIs
  • REST URLs in SharePoint 15

Making REST calls with C# and JavaScript for SharePoint 2013

  • Returning ATOM XML vs JSON
    • SharePoint returns REST based data in two formats – ATOM XML and JSON
    • ATOM XML is preferred format in .NET Managed code and JSON is preferred format in JavaScript
    • To get ATOM XML, response use MIME type “application/atom+xml”, This is ideal for .NET managed code, you can also use in JavaScript but use XSLT in conjunction with parsing XML to format it properly
    • To get JSON, response use MIME type “application/json”, ideal in JavaScript in conjunction with jQuery
    • Response data format selected in ACCEPT header, ATOM XML is default option for data format returned by REST based calls in SharePoint, for JSON response, you must pass “application/json” MIME type in ACCEPT header
  • REST Query from Managed code – Tips for making REST calls from managed code
    • in .NET 4.0 or later, use the HTTPWebRequest and HTTPWebResponse objects instead of WebRequest or WebResponse classes which would allow you to specify Accept property for required MIME string
    • Use LINQ-to-XML to get data from XML in response body by loading XML response stream in XDocument object and using XDocument.Descendants method to query data
  • REST Query using JavaScript and jQuery
    • Use #.getJSON to request the JSON response if you are using jQuery
  • Updating using REST based API and Form Digest
    • Updates using REST requires Form Digest to protect against replay attack
    • Form Digest is available on the SharePoint since MOSS 2007 days, Form Digest is a special value created using cryptography, SharePoint Pages have control holding Form Digest
    • The Form Digest control does this by using cryptography to create a special value that is passed to the client browser. This value must be passed back to SharePoint and validated on requests that update objects or content within a SharePoint site
    • Add X-RequestDigest header which includes value of form digest
      • In the Managed code, form digest can be acquired through _vti_bin/sites.asmx and pass it to the REST based call,
      • In the JavaScript, assign the value from the control – $(“#_REQUESTDIGEST).val()
About these ads
This entry was posted in SP2013 DEV. Bookmark the permalink.

One Response to What’s New in SharePoint 2013 CSOM and REST APIs

  1. Vn ABC says:

    Even though this article was from last year, but I found it’s very helpful and very informative. Thanks

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s