Introduction to the SharePoint Client Object Model and REST API

Introduction to the SharePoint 2013 Client Object
Model and REST API
Rob Windsor
rob@robwindsor.com
@robwindsor

About Me
 Senior SharePoint Consultant
 Technical Contributor to the Pluralsight On-Demand Library
 Microsoft MVP, MCPD, MCT
 Founder and Past-President of the North Toronto .NET UG
 Co-author of Prof. Visual Basic 2012 and .NET 4.5 (Wrox)

Client Object Model (CSOM)
 API used when building remote applications
 Designed to be similar to the Server Object Model
 Introduced in SharePoint 2010, expanded in SharePoint 2013
 Slightly different versions for SP 2013 on-premises and SP Online
 Three implementations
 .NET Managed, Silverlight (plus Mobile), JavaScript
 Façades on top of /_vti_bin/Client.svc
 Managed implementation has two versions
 Version 15 is for use against an on-premises farm
 Version 16 is for use against SharePoint Online
 Communication with SharePoint done in batches

Client Object Model Coverage
 Sites, Webs, Features, Event Receivers
 Lists, List Items, Fields, Content Types, Views, Forms
 Files, Folders
 Users, Roles, Groups, User Profiles, Feeds
 Web Parts
 Search
 Taxonomy
 Workflow
 IRM
 E-Discovery
 Analytics
 Business Data

Communicating with SharePoint
 All CRUD operations are automatically batched
 Requests for resources batched using Load and LoadQuery methods
 Batches are executed using ExecuteQuery or ExecuteQueryAsync
 This triggers a POST request to Client.svc/ProcessQuery
 Message body contains XML document with batched request information
 Response contains requested resources in JSON format

Client Object Model Authentication
 .NET Managed
 Windows credentials passed by default
 ClientContext.AuthenticationMode
 Default
 Anonymous
 FormsAuthentication
 ClientContext.Credentials
 Expects System.Net.ICredentials
 NetworkCredential, SharePointOnlineCredentials, …
 ClientContext.FormsAuthenticationLoginInfo
 Silverlight and JavaScript
 Credentials of the hosting Web application are always used

Retrieving Resources Using Load
var context = new ClientContext(siteUrl)
var web = context.Web;
context.Load(web);
context.Load(web.Lists);
context.ExecuteQuery();
ResultsListBox.Items.Add(web.Title);
ResultsListBox.Items.Add(web.Lists.Count);
 Indicates object data should be included in next batch retrieval
 Not all property values are retrieved
 Example: collections of associated objects
var context = SP.ClientContext.get_current();
var web = context.get_web();
var lists = web.get_lists();
context.load(web);
context.load(lists);
context.executeQueryAsync(success, fail);
function success() {
var div = jQuery("#message");
div.text(web.get_title());
div.append("<br />");
div.append(lists.get_count());
}
Managed: JavaScript:

Retrieving Resources Using LoadQuery
(Managed Code)
var query = from list in web.Lists
where list.Hidden == false &&
list.ItemCount > 0
select list;
var lists = context.LoadQuery(query);
Console.WriteLine(lists.Count());
 Indicates result of query should be included in next batch
retrieval
 Query executed on server
 Result returned from call
 Not loaded in-place as with Load

Retrieving Resources Using loadQuery
(JavaScript)
var lists = context.get_web().get_lists();
context.load(lists);
div.text(lists.get_count());
}
 No LINQ in JavaScript
 loadQuery very similar to load
 Returns new object
 Returns array for collections
var lists = context.get_web().get_lists();
var myLists = context.loadQuery(lists);
div.text(myLists.length);
}
load: loadQuery:

Selecting Fields to Retrieve
context.Load(web, w => w.Title, w => w.Description);
var query = from list in web.Lists.Include(l => l.Title)
where list.Hidden == false &&
list.ItemCount > 0
select list;
var lists = context.LoadQuery(query);
 Limit fields returned to reduce network traffic
 Use parameter array in Load and LoadQuery
 Use Include for collections
var lists = web.get_lists();
context.load(web, "Title", "Description");
context.load(lists, "Include(Title)");

Retrieving List Items
 Somewhat different than Server OM
 Set of items accessed by List.GetItems method
 Forces use of CAML query to encourage reduced result sets
 Selecting fields to be returned
 Can use ViewFields in query
 Can use Include with Load or LoadQuery
 CSOM does not support cross-list CAML queries
 Can use KeywordQuery with Search API for similar results
Task Server OM Managed Client OM
Get list web.Lists[“Products”] web.Lists.GetByTitle(“Products”)
Get items list.Items list.GetItems(query)
Get item title item.Title item[“Title”]
Query type SPQuery CamlQuery

Using CAML Queries
var list = web.Lists.GetByTitle("Products");
var query = new CamlQuery();
query.ViewXml = "<View>" +
"<Query>" +
"<Where><Eq>" +
"<FieldRef Name='Category' " +
"LookupId='True' />" +
"<Value Type='Lookup'>1</Value>" +
"</Eq></Where>" +
"</Query>" +
"</View>";
var items = list.GetItems(query);
context.Load(items,
c => c.Include(li => li["ID"], li => li["Title"]));
var list = web.get_lists().getByTitle("Products");
var query = new SP.CamlQuery();
query.set_viewXml("<View>" +
"<Query>" +
"<Where><Eq>" +
"<FieldRef Name='Category' " +
"LookupId='True' />" +
"</Eq></Where>" +
"</Query>" +
"<RowLimit>5</RowLimit>" +
"</View>");
var items = list.getItems(query);
context.load(web, "Title");
context.load(items, "Include(ID, Title)");

REST API
 API used when building remote applications
 What is the REST API in SharePoint
 Data-centric web services based on the Open Data Protocol (OData)
 Each resource or set of resources is addressable
 http://<site url>/_api/web
 http://<site url>/_api/web/lists
 http://<site url>/_api/web/lists/getByTitle(‘Customers’)
 http://<site url>/_api/web/lists/getByTitle(‘Customers’)/items
 Operations on resources map to HTTP Verbs
 GET, PUT, POST, DELETE, …
 Results from service returned in AtomPub (XML) or JavaScript Object
Notation (JSON) format

REST API History
 SharePoint 2010
 Initial REST API added
 /_vti_bin/ListData.svc
 Exposed CRUD operations on list data
 SharePoint 2013
 REST API expands and evolves
 ListData.svc deprecated
 Still available for backwards compatibility
 RESTful operations added to /_vti_bin/Client.svc
 /_api added as an alias for /_vti_bin/Client.svc

REST API Coverage
 Sites, Webs, Features, Event Receivers
 Lists, List Items, Fields, Content Types, Views, Forms, IRM
 Files, Folders
 Users, Roles, Groups, User Profiles, Feeds
 Search
 No support for Managed Metadata
 Term Store or Managed Metadata Fields
 No support for Workflow

Retrieving Data (Managed)
 Service metadata for /_api was added around April 2013
 You can add a service reference in Visual Studio
 Tooling to add a service reference for SharePoint Online does not work
 Service proxy contains two context classes
 SP.Data.ListData – access to list data
 SP.ApiData – access to everything else
 Generated proxy classes do not natively support updates
 SharePoint REST API works differently than OData
 Need to use POST tunneling and client hooks to get updates to work
 Too much work – better off using CSOM
 For more detail see white paper by Paul Schaelein
 SharePoint 2013 REST and WCF Data Services
 http://www.schaeflein.net/Pages/SharePoint-2013-REST-and-WCF-
Data-Services.aspx
 Still have the option of using the 2010 version of REST API

var svcUri = new Uri(siteUrl + "/_api");
var context = new SP2013Proxy.SP.ApiData(svcUri);
context.Credentials = System.Net.CredentialCache.DefaultCredentials;
var resourceUri = new Uri("/web", UriKind.Relative);
var webs = context.Execute<SP2013Proxy.SP.Web>(resourceUri);
var web = webs.First();
ResultsListBox.Items.Add(web.Title);

 Have option of doing HTTP requests
 Need to work with raw XML or JSON
var url = siteUrl + "/_api/Web/";
var client = new WebClient();
client.UseDefaultCredentials = true;
client.Headers[HttpRequestHeader.Accept] = "application/json;odata=verbose";
var json = client.DownloadString(url);
var ser = new JavaScriptSerializer();
dynamic item = ser.Deserialize<object>(json);
ResultsListBox.Items.Add(item["d"]["Title"]);

Retrieving Data (JavaScript)
 Use jQuery to make service call
 Use _spPageContextInfo to get site URL
 Use Accept header to request JSON response
var call = jQuery.ajax({
url: _spPageContextInfo.webAbsoluteUrl + "/_api/Web/",
type: "GET",
dataType: "json",
headers: {
Accept: "application/json;odata=verbose"
}
});
call.done(function (data, textStatus, jqXHR) {
div.text(data.d.Title);
});
call.fail(function (jqXHR, textStatus, errorThrown) {
alert("Call failed. Error: " + errorThrown);
});

OData Queries
 Queries represented by query strings added to resource URL
Option Example
$select _api/Web/Lists?$select=Title,ItemCount
$filter _api/Web/Lists?$filter=(Hidden eq false)
$orderby _api/Web/Lists?$orderby=ItemCount desc
$skip, $top _api/Web/Lists?$skip=25&$top=10
$expand _api/Web/Lists?$expand=Fields
Full documentation: http://www.odata.org/documentation/odata-v2-documentation/
uri-conventions/#4_Query_String_Options (http://bit.ly/10dqevp)

OData Continuations
 OData provider may limit number of item in response
 Need to check for __next (JSON) or link element (AtomPub)
 Use URL to get next set of results

CAML Queries
 Must be executed using a POST
 Headers must include Form Digest
var viewXml = { ViewXml: "<View>" +
"<Query>" +
"<Where><Eq>" +
"<FieldRef Name='Category' LookupId='True' />" +
"</Eq></Where>" +
"</Query>" +
"</View>"
}
url: _spPageContextInfo.webAbsoluteUrl +
"/_api/Web/Lists/getByTitle('Products')/GetItems(query=@v1)?" +
@v1=" + JSON.stringify(viewXml),
type: "POST",
dataType: "json",
headers: {
Accept: "application/json;odata=verbose",
"X-RequestDigest": jQuery("#__REQUESTDIGEST").val()
}
});

Form Digest
 Protects against replay attacks
 Value available in hidden field on SharePoint page
 Unique to user and site
 Only valid for limited time
 Use UpdateFormDigest() function to refresh value in hidden
field
 Service call only make if form digest has expired
 For more details see blog post by Wictor Wilen
 How to refresh the Request Digest value in JavaScript
 http://www.wictorwilen.se/sharepoint-2013-how-to-refresh-the-request-
digest-value-in-javascript

Creating a List (CSOM)
 Moderately different than code for Server Object Model
 Adding the list
 Web.Lists.Add(creationInformation)
 Parameter is type ListCreationInformation
var lci = new ListCreationInformation();
lci.Title = "Tasks";
lci.QuickLaunchOption = QuickLaunchOptions.On;
lci.TemplateType = (int)ListTemplateType.Tasks;
var list = web.Lists.Add(lci);
var lci = new SP.ListCreationInformation();
lci.set_title("Tasks");
lci.set_quickLaunchOption(SP.QuickLaunchOptions.on);
lci.set_templateType(SP.ListTemplateType.tasks);
var list = web.get_lists().add(lci);

Creating a List (REST)
 Send POST to /_api/Web/Lists
 Message body has SP.List object with properties
 Fills same role as SP.ListCreationInformation object in CSOM
 Must include Form Digest in headers
url: _spPageContextInfo.webAbsoluteUrl + "/_api/Web/Lists",
type: "POST",
data: JSON.stringify({
"__metadata": { type: "SP.List" },
BaseTemplate: SP.ListTemplateType.tasks,
Title: "Tasks"
}),
headers: {
"Content-Type": "application/json;odata=verbose",
}
});

Creating and Updating List Items (CSOM)
 Virtually the same as code for Server Object Model
 Adding a list item
 List.AddItem(creationInformation)
 Parameter is type ListItemCreationInformation
 Updating field values
 Exactly the same as Server Object Model code
var list = web.Lists.GetByTitle("Tasks");
var ici = new ListItemCreationInformation();
var item = list.AddItem(ici);
item["Title"] = "Sample Task";
item["AssignedTo"] = web.CurrentUser;
item["DueDate"] = DateTime.Now.AddDays(7);
item.Update();
var list = web.get_lists().getByTitle("Tasks");
var ici = new SP.ListItemCreationInformation();
var item = list.addItem(ici);
item.set_item("Title", "Sample Task");
item.set_item("AssignedTo", web.get_currentUser());
var due = new Date();
due.setDate(due.getDate() + 7);
item.set_item("DueDate", due);
item.update();

Creating List Items (REST - JavaScript)
 Post to /_api/Web/Lists/getByTitle(‘<List Name>’)/Items
 Type name is SP.Data.<List Name>ListItem
url: _spPageContextInfo.webAbsoluteUrl + "/_api/Web/Lists/getByTitle('Tasks')/Items",
type: "POST",
"__metadata": { type: "SP.Data.TasksListItem" },
Title: "Sample Task",
AssignedToId: userId,
DueDate: due
}),
headers: {
}
});

Creating List Items (REST - Managed)
 Create instance of list item type
 One of the generated types in the service proxy
 Set property values
 Add to list using the AddTo<list name> method on context
var svcUri = new Uri(siteUrl + "/_vti_bin/ListData.svc");
var context = new SP2010Proxy.DemoDataContext(svcUri);
var item = new SP2010Proxy.ProductsItem();
item.Title = "Test Product";
item.ProductID = 999;
item.CategoryId = 1;
item.UnitPrice = 9.99;
item.UnitsInStock = 99;
context.AddToProducts(item);
context.SaveChanges();

Updating List Items (REST - Managed)
 Get list item
 Update property values
 Call UpdateObject on context
var svcUri = new Uri(siteUrl + "/_vti_bin/ListData.svc");
var context = new SP2010Proxy.DemoDataContext(svcUri);
var query = from product in context.Products
where product.ProductID == 999
select product;
var item = query.FirstOrDefault();
if (item != null)
{
item.UnitPrice = 4.44;
item.UnitsInStock = 44;
context.UpdateObject(item);
context.SaveChanges();
}

Updating List Items (REST - JavaScript)
 Send to /_api/Web/Lists/getByTitle(‘<List>')/Items(<Item Id>)
 Request type (X-Http-Method)
 Can update by sending PUT
 All writable field values must be specified
 Can update by sending POST
 Set X-Http-Method to PATCH or MERGE
 Only send field values that are changing
 Concurrency (IF-MATCH)
 Item metadata includes etag which represents the version
 Set IF-MATCH in header to etag value
 Update will fail if item has been updated since read
 SET IF-MATCH in header to *
 Update will overwrite changes (if any)

Updating List Items (REST - JavaScript)
url: _spPageContextInfo.webAbsoluteUrl +
"/_api/Web/Lists/getByTitle('Tasks')/Items(" + item.Id + ")",
type: "POST",
"__metadata": { type: "SP.Data.TasksListItem" },
Status: "In Progress",
PercentComplete: 0.10
}),
headers: {
"X-RequestDigest": jQuery("#__REQUESTDIGEST").val(),
"IF-MATCH": item.__metadata.etag,
"X-Http-Method": "PATCH"
}
});

Thank You
 Big thanks to the organizers, sponsors and you for
making this event possible
 Please fill out your evaluation
 Please keep in touch
rob@robwindsor.com
@robwindsor
blogs.msmvps.com/windsor

Introduction to the SharePoint Client Object Model and REST API

Related slideshows

More Related Content

Introduction to the SharePoint Client Object Model and REST API

Editor's Notes