SharePoint 2013 REST APIs
Download as PPTX, PDF2 likes4,271 views
The document discusses the REST API in SharePoint 2013. It provides an overview of REST and how it is implemented in SharePoint. Key points include how the REST API provides another way to access SharePoint data through HTTP requests, how the API syntax uses the _api endpoint and OData queries, and examples of performing basic CRUD operations through the API. Limitations of the API are also outlined.
SharePoint 2013 REST APIs
- 1. 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
- 2. Grazie a Sponsor #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 3. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 4. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 5. 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# #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 6. What’s REST in SharePoint? #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 7. 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! #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 8. 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! #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 9. 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! #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 10. demo Our first call to SharePoint 2013 REST APIs #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 11. 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) #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 12. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 13. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 14. demo Let’s play with _api #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 15. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 16. 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) #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 17. 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! #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 18. demo How to compone a query #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 19. 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) { //... } }); #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 20. 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); #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 21. 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) { //... } }); #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 22. 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) { //... } }); #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 23. 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? #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 24. 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(); #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 25. 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. #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 26. Basic operations - Delete #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 27. 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) #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 28. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 29. BELLA! www.peppedotnet.it www.dev4side.com #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 30. 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! #CDays14 – Milano 25, 26 e 27 Febbraio 2014
- 31. 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 #CDays14 – Milano 25, 26 e 27 Febbraio 2014