SharePoint 2013 REST APIs

SHA02 – Le REST API
di SharePoint 2013
Giuseppe Marchi
Dev4Side S.r.l. – SharePoint MVP
info@peppedotnet.it - @PeppeDotNet
http://www.peppedotnet.it
http://www.dev4side.com
#CDays14 – Milano 25, 26 e 27 Febbraio 2014

Grazie a
Sponsor


Who I am
•

Co-founder of Dev4Side S.r.l.

•

4 years Microsoft SharePoint MVP

•

Speaker in Microsoft and Community events in Italy

•

MCP, MCPD Web applications, MCTS ASP.NET 4, WSS 3.0, MOSS 2007 and
SharePoint 2010

•

"SharePointer" from 2005

•

Father of www.peppedotnet.it 

•

Author of the book «Pocket C#», Apogeo

•

Active member, speaker and promoter of SharePointCommunity.it

•

First, in Italy, with an App in the Office Store

•

One of the TOP 25 SharePoint Influencers in Europe


Agenda
•

What’s REST?

•

What’s REST in SharePoint

•

SharePoint 2013 API changes
 What’s new with REST interface

•

New REST APIs syntax

•

Basic operators and actions

•

General tips

•

Known limits


What’s REST?
•

REST = Representational State Transfer
 It’s an architecture style for designing networked applications
 RESTful applications use HTTP requests to post data (create and/or update),
read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all
four CRUD (Create/Read/Update/Delete) operations.
 REST is a lightweight alternative to Web Services

•

It’s an architectural style, awesome for cross-platform apps

•

Easier and smaller than SOAP

•

Easy to use with Javascript, than C#


What’s REST in SharePoint?


What’s REST in SharePoint?
•

It’s another way to consume data, use all the advanced services and
functionalities exposed by SharePoint from your own client applications

•

in a secure way

•

… all done with a simple HTTP request!


What we had in the past?
•

MOSS 2007
 SOAP Services

•

SharePoint 2010
 SOAP Services
 Client Object Model





Direct access to client.svc service
Request always in XML
Must use a proxy
Supports only .NET, Silverlight and Javascript

 REST Interface (ListData.svc)
 Only for lists!


What we have now – New REST APIs
•

Direct access to client.svc service (using _api alias)

•

Access HTTP GET, PUT, Merge, POST Requests

•

OData implementation*

•

Atom XML or JSON as data type

•

Supports any application, language or platform that enables you to do a
HTTP request

 You can access to a lot of features of the Client Object Model through an HTTP
request!


demo
Our first call to SharePoint 2013 REST APIs


Entry points
REST service includes several access points that enable developers to
navigate to specific functionality of SharePoint 2013. The table below lists
some of these access points.
Feature area

Entry point

Context

http://server/site/_api/contextInfo

Site

http://server/site/_api/site

Web

http://server/site/_api/web

User profile

http://server/site/_api/SP
.UserProfiles.PeopleManager

Search

http://server/site/_api/search

Publishing

http://server/site/_api/publishing

Excel services (new and

http://server/site/_vti_bin/ExcelRest.aspx

only on SharePoint Online)


URL syntax for REST calls
•

A request to the new REST interface shall use an URL composed in the
following way:
 Part 1 - Service root URI
 Es: http://siteurl/_api/

 Part 2 - Resource path (default entry point + resource)
 Es: web, site collection, list, file, sql table, user, namespace, method, etc…

 Part 3 - Query strings options (OData operators)
 Es: $filter, $select, etc…

Full documentation on MSDN:

http://msdn.microsoft.com/en-us/library/office/dn292556.aspx


Allowed HTTP methods
•

Each REST command is a POST, GET, PUT, MERGE or DELETE HTTP
request (mapping to CRUD) where the specific resource is in the URL
and into request data





READ -> GET HTTP request
CREATE -> HTTP POST request
UPDATE -> HTTP POST PUT or HTTP POST MERGE request
DELETE -> HTTP DELETE request


demo
Let’s play with _api


Sample URLs
http://siteurl/_api/web
http://siteurl/_api/web/lists
http://siteurl/_api/web/lists?$filter=BaseTemplate eq 101
http://siteurl/_api/web/lists?$orderby=Title asc
http://siteurl/_api/web/lists?$top=5&$skip=5
http://siteurl/_api/web/lists?$filter=startswith(Title, 'Shared')
http://siteurl/_api/web/lists/getByTitle('Contacts')
http://siteurl/_api/web/lists/getByTitle('Contacts')/items
http://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)
http://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)/Title
http://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)?$select=Title
http://siteurl/_api/web/lists/getbytitle('shared documents')/rootfolder/folders?$select=Name
http://siteurl/_api/web/getFolderByServerRelativeUrl('/Shared documents/Folder1/Folder2')
http://siteurl/_api/web/getFolderByServerRelativeUrl('Shared documents')/Folders/add(url=''New
folder')
http://siteurl/_api/Web/getFolderByServerRelativeUrl('Shared
documents')/Files/add(url='NewFile.txt', overwrite=true)
http://siteurl/_api/web/currentuser/email


How to find resource path?
•

Start from /_api/web!

•

Client object model reference

•

List of assemblies: 15/config/clientcallable xml files

•

SPRemoteAPIExplorer Visual Studio Extension

•

REST Navigator
(http://sprest.architectingconnectedsystems.com/navigator.aspx)


How to compone a query
•

In order to use the new REST interface in SharePoint 2013, you have to create
an HTTP request using these parameters:






URL – URI of the resource you want to manage
Request type – GET/POST
Data - parameters for POST queries
ContentType – Content type of Data (XML/JSON), default: XML
Headers





•

Accept – Content type of the response (XML/JSON), default: XML
X-RequestDigest – Security token
X-HTTP-Method – PUT/MERGE/DELETE
IF-MATCH – To manage concurrency

Note: you can do this HTTP request from every platform or programming
language!


demo
How to compone a query


Basic operations – Read (Javascript)
$.ajax({
url: '/_api/web/lists/getByTitle('LIST NAME')/items',
type: 'GET',
headers: {
'Accept': 'application/json;odata=verbose',
},
success: function (data) {
$.each(data.d.results, function(index, items) {
//...
}
},
error: function (jqXHR, textStatus, errorThrown) {
//...
}
});


Basic operations – Read (C#)
//url
string url = "http://sp2013/_api/web/lists?$select=Title";
//credenziali
CredentialCache credentials = new CredentialCache();
credentials.Add(new Uri(url), "NTLM", CredentialCache.DefaultNetworkCredentials);
//richiesta HTTP
HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(url);
request.Credentials = credentials;
request.Method = "GET";
request.Accept = "application/atom+xml;odata=verbose";
request.ContentLength = 0;
//lettura risposta HTTP
Stream postStream;
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
string results = GetHTTPResponse(response, out postStream, out results);
XmlDocument doc = new XmlDocument();
doc.LoadXml(results);
XmlNamespaceManager namespaces = new XmlNamespaceManager(new NameTable());
namespaces.AddNamespace("d", "http://schemas.microsoft.com/ado/2007/08/dataservices");
var lists = doc.SelectNodes("//d:Title", namespaces);
foreach (XmlNode list in lists)
Console.WriteLine(list.InnerText);


Basic operations - Insert
$.ajax({
type: 'POST',
data: JSON.stringify(JSON OBJECT),
contentType: 'application/json;odata=verbose',
headers: {
'content-type': 'application/json;odata=verbose',
'X-RequestDigest': 'DIGEST VALUE'
},
//...
},
//...
}
});

Basic operations - Insert
$.ajax({
type: 'POST',
data: JSON.stringify(JSON OBJECT),
headers: {
'content-type': 'application/json;odata=verbose',
'X-RequestDigest': 'DIGEST VALUE' //??????????????
},
//...
},
//...
}
});

The digest
•

It’s a token that enables SharePoint to validate current user session

•

It’s required for every POST call to REST APIs in which you change data
(INSERT, UPDATE, DELETE) and shall be the value of the HTTP header:
 X-RequestDigest

•

Where we can find this value?


The digest – How to find it?
OPTION 1

var formDigest = '';
$.ajax({
url: http://siteurl/_api/contextinfo
type: 'POST',
headers: { 'Accept': 'application/json;odata=verbose'},
formDigest = data.d.GetContextWebInformation.FormDigestValue;
},
alert(errorThrown);
},
async: false
});
OPTION 2
var formDigest = $('__REQUESTDIGEST').val();

Basic operations - Update

Note: For MERGE requests,
setting properties is
optional; any properties
that you do not explicitly
set retain their current
property. For PUT
requests, if you do not
specify all required
properties in object
updates, the REST service
returns an exception.


Basic operations - Delete


General tips
•

Limit response length!
 Request only data that you want to use, with the $select parameter
 Paginate response where you can
 Use JSON (you get a smaller payload)

•

Limit the number of requests
 Remember that you are a client and that the request comes from a server

•

Request data in async way

•

Take care of concurrency (using IF-MATCH header)


Known limits
•

Operations are a subset of the Client Object Model
 Client Object Model is a subset of the Server Object Model…

•

No request batching

•

No elevation of privilegies

•

OData is not fully implemented

•

256 characters for URLs

•

Items pagination with $top and $skip it’s bugged


BELLA! 
www.peppedotnet.it
www.dev4side.com


Do you SharePoint?
•

SharePoint & Office Conference 2014
 27-28 Maggio 2014

•

http://www.sharepointconference.it/

•

Perché non puoi mancare





•

I migliori speaker italiani ed internazionali
30 sessioni tecniche + video registrati
Roundtable
Ask the Expert

Super Early Bird fino al 28 Marzo 2014!


Q&A
Tutto il materiale di questa sessione su
http://www.communitydays.it/
Lascia il feedback su questa sessione,

potrai essere estratto per i nostri premi!
Seguici su
Twitter @CommunityDaysIT
Facebook http://facebook.com/cdaysit
#CDays14


SharePoint 2013 REST APIs

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to SharePoint 2013 REST APIs

Similar to SharePoint 2013 REST APIs (20)

More from Giuseppe Marchi

More from Giuseppe Marchi (12)

Recently uploaded

Recently uploaded (20)

SharePoint 2013 REST APIs