SharePoint 2013 REST APIs

#CDays14 – Milano 25, 26 e 27 Febbraio 2014

SHA02 – Le REST API di SharePoint 2013

Giuseppe MarchiDev4Side S.r.l. – SharePoint MVP

[email protected] - @PeppeDotNet

http://www.peppedotnet.ithttp://www.dev4side.com


Grazie a

Sponsor

http://www.aspitalia.com/

http://www.domusdotnet.org/

http://www.dotdotnet.org/

http://www.dotnetcampania.org/

http://www.dotnetliguria.net/

http://www.dotnetside.org/

http://www.ugidotnet.org/


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)

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

• 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


demoOur first call to SharePoint 2013 REST APIs


Entry pointsREST 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 only on SharePoint Online)

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


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


demoLet’s play with _api


Sample URLshttp://siteurl/_api/webhttp://siteurl/_api/web/listshttp://siteurl/_api/web/lists?$filter=BaseTemplate eq 101http://siteurl/_api/web/lists?$orderby=Title aschttp://siteurl/_api/web/lists?$top=5&$skip=5http://siteurl/_api/web/lists?$filter=startswith(Title, 'Shared')http://siteurl/_api/web/lists/getByTitle('Contacts')http://siteurl/_api/web/lists/getByTitle('Contacts')/itemshttp://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)http://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)/Titlehttp://siteurl/_api/web/lists/getByTitle('Contacts')/items(1)?$select=Titlehttp://siteurl/_api/web/lists/getbytitle('shared documents')/rootfolder/folders?$select=Namehttp://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)

RESOURCE PATH

Client Object Model APIs

1 ~ 1


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!


demoHow 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#)//urlstring url = "http://sp2013/_api/web/lists?$select=Title";

//credenzialiCredentialCache credentials = new CredentialCache();credentials.Add(new Uri(url), "NTLM", CredentialCache.DefaultNetworkCredentials);

//richiesta HTTPHttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(url);request.Credentials = credentials;request.Method = "GET";request.Accept = "application/atom+xml;odata=verbose";request.ContentLength = 0;

//lettura risposta HTTPStream 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({ url: '/_api/web/lists/getByTitle(\'LIST NAME\')/items', type: 'POST', data: JSON.stringify(JSON OBJECT), contentType: 'application/json;odata=verbose', headers: { 'content-type': 'application/json;odata=verbose', 'Accept': 'application/json;odata=verbose', 'X-RequestDigest': 'DIGEST VALUE' }, success: function (data) { //... }, error: function (jqXHR, textStatus, errorThrown) { //... }});


Basic operations - Insert$.ajax({ url: '/_api/web/lists/getByTitle(\'LIST NAME\')/items', type: 'POST', data: JSON.stringify(JSON OBJECT), contentType: 'application/json;odata=verbose', headers: { 'content-type': 'application/json;odata=verbose', 'Accept': 'application/json;odata=verbose', 'X-RequestDigest': 'DIGEST VALUE' //?????????????? }, success: function (data) { //... }, error: function (jqXHR, textStatus, errorThrown) { //... }});


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', contentType: 'application/json;odata=verbose', headers: { 'Accept': 'application/json;odata=verbose'}, success: function (data) { formDigest = data.d.GetContextWebInformation.FormDigestValue; }, error: function (jqXHR, textStatus, errorThrown) { alert(errorThrown); }, async: false });

OPTION 2

var formDigest = $('__REQUESTDIGEST').val();


Basic operations - Update$.ajax({ url: 'http://siteurl/_api/web/lists/getByTitle(\'LIST NAME\')/items(ITEM ID)', type: 'POST', data: JSON.stringify(JSON MODIFIED OBJECT), contentType: 'application/json;odata=verbose', headers: { 'content-type': 'application/json;odata=verbose', 'Accept': 'application/json;odata=verbose', 'X-RequestDigest': 'DIGEST VALUE', 'X-HTTP-Method': 'MERGE', //or PUT 'IF-MATCH': '*' }, success: function (data) { //... }, error: function (jqXHR, textStatus, errorThrown) { //... }});

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$.ajax({ url: 'http://siteurl/_api/web/lists/getByTitle(\'LIST NAME\')/items(ITEM ID)', type: 'POST', contentType: 'application/json;odata=verbose', headers: { 'content-type': 'application/json;odata=verbose', 'Accept': 'application/json;odata=verbose', 'X-RequestDigest': 'DIGEST VALUE', 'X-HTTP-Method': 'DELETE', 'IF-MATCH': '*' }, success: function (data) { //... }, error: function (jqXHR, textStatus, errorThrown) { //... }});


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.itwww.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!

http://www.sharepointconference.it/


Q&ATutto 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

http://www.communitydays.it/

SharePoint 2013 REST APIs

Technology

Transcript of SharePoint 2013 REST APIs