understanding the rest api of sharepoint 2013
DESCRIPTION
Presented by Paolo Pialorsi at SharePoint Saturday Stockholm 2014 See also http://www.spsstockholm.com/2014/session/understanding-the-rest-api-of-sharepoint-2013/ From a developer perspective, one of the most important new features introduced in Microsoft SharePoint 2013 is the REST API. In this session, you learn about the architecture of the REST API, the main and most useful endpoints, and you see a bunch of real-life usage samples to leverage the API in your SharePoint Apps. To attend this session you should have a good understanding of developing SharePoint Apps.TRANSCRIPT
![Page 1: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/1.jpg)
Understanding the REST API of SharePoint 2013
#SPSSTHLM17Paolo Pialorsi – [email protected] 25th, 2014
SharePoint Saturday
Stockholm
![Page 2: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/2.jpg)
Thanks to our sponsors!
SharePint
Silver
Bronze
Raffle
Platinum
Gold
![Page 3: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/3.jpg)
Something about me Consultant, project manager and trainer since
1996 Company of my own: www.pialorsi.com
More than 40 Microsoft certification exams passed Microsoft Certified Solution Master – Charter SharePoint
Focused on SharePoint since 2002 Author of 10 books about XML, SOAP, .NET, LINQ
and SharePoint Microsoft SharePoint 2010 Developer Reference, Microsoft Press Microsoft SharePoint 2013 Developer Reference, Microsoft Press Build Windows 8 Apps with Microsoft Visual C# and
Visual Basic Step by Step, Microsoft Press
Speaker at main IT conferences
![Page 4: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/4.jpg)
Agenda• _api Architecture• Querying data• Managing data• Cross domain calls• Security
![Page 5: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/5.jpg)
_API architectureLet’s see how it works
![Page 6: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/6.jpg)
JavaScript Library
Silverlight Library
.Net CLR Library
Custom Client Code
Client
Server
_api is new alias for _vti_bin/client.svc
_api Architecture
RESTODataJSON
CSOM
![Page 7: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/7.jpg)
_api Consumers
![Page 8: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/8.jpg)
DEMOSome sample URI endpoints
![Page 9: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/9.jpg)
Sample URLs _api/web/lists _api/web/lists/getByTitle(‘Documents') _api/web/Lists/getByTitle('Documents')/Items _api/web/Lists/getByTitle('Documents')/Items(4) _api/web/CurrentUser _api/web/SiteUsers _api/web/getAvailableWebTemplates(lcid=1033) _api/web/RoleAssignments/GetPrincipalId(1)/Member
![Page 10: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/10.jpg)
Living in a REST-ful world REST = Representational State Transfer Main capabilities and features
Lighter than SOAP Easier to consume from jQuery/JavaScript
Can leverage either JSON or ATOM for data representation Cross-platform URL based Securable through OAuth or HTTP security
![Page 11: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/11.jpg)
Supported HTTP methods GET: read operations POST: creation operations PUT: data modification (update)
All the required fields are mandatory
PATCH, MERGE: POST + X-Http-Method header MERGE for backward compatibility only Use PATCH, instead
DELETE: POST + X-Http-Method header
![Page 12: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/12.jpg)
DEMOConsuming REST API from a developer perspective
![Page 13: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/13.jpg)
_api Reference
http(s)://{Host Name}/{site}/_api/{namespace}/
{object}{property}{indexer(index)}{method({parameter},{parameter},…)}
Web Application Hostname
Site Collection (Optional)
API Namespace
Operation
![Page 14: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/14.jpg)
Main namespaces site web SP.UserProfiles.PeopleManager ContextInfo search publishing social.feed
![Page 15: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/15.jpg)
Querying dataLet’s read some real data …
![Page 16: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/16.jpg)
_api is OData compliant Available query string arguments
$filter $select $orderby $top $skip $expand
![Page 17: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/17.jpg)
Logical OperationsOperator Description Example
eq Equal /Suppliers?$filter=Address/City eq 'Redmond'
ne Not equal /Suppliers?$filter=Address/City ne 'London'
gt Greater than /Products?$filter=Price gt 20
ge Greater than or equal /Products?$filter=Price ge 10
lt Less than /Products?$filter=Price lt 20
le Less than or equal /Products?$filter=Price le 100
and Logical and /Products?$filter=Price le 200 and Price gt 3.5
or Logical or /Products?$filter=Price le 3.5 or Price gt 200
not Logical negation /Products?$filter=not endswith(Description,'milk')
![Page 18: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/18.jpg)
Arithmetic Operators
Operator Description Example
add Addition /Products?$filter=Price add 5 gt 10
sub Subtraction /Products?$filter=Price sub 5 gt 10
mul Multiplication /Products?$filter=Price mul 2 gt 2000
div Division /Products?$filter=Price div 2 gt 4
mod Modulo /Products?$filter=Price mod 2 eq 0
![Page 19: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/19.jpg)
Functions (1/3)Function Description Example
bool substringof(string searchString, string searchInString)
Returns a boolean value stating if the value provided in the first argument is a substring of the second argument. Can be used as a replacement for the contains method.
substringof('Alfreds',CompanyName)
bool endswith(string string, string suffixString)
Returns a boolean value declaring if the string provided in the first argument ends with the string provided in the second argument.
endswith(CompanyName,'Futterkiste')
bool startswith(string string, string prefixString)
Returns a boolean value declaring if the string provided in the first argument starts with the string provided in the second argument.
startswith(CompanyName,'Alfr')
int length(string string)Returns an integer value representing the length of the string provided as argument.
length(CompanyName) eq 19
int indexof(string searchInString, string searchString)
Returns an integer value representing the index of the string provided in the second argument, which is searched within the string provided in the first argument.
indexof(CompanyName,'lfreds') eq 1
string replace(string searchInString, string searchString, string replaceString)
Replaces the string provided in the second argument with the string provided in the third argument, searching within the first string argument.
replace(CompanyName,' ', '') eq 'AlfredsFutterkiste'
string substring(string string, int pos)
Returns a substring of the string provided in the first argument, starting from the integer position provided in the second argument.
substring(CompanyName,1) eq 'lfreds Futterkiste'
![Page 20: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/20.jpg)
Functions (2/3)Function Description Example
string substring(string string, int pos, int length)
Returns a substring of the string provided in the first argument, starting from the integer position provided in the second argument and stopping after a number of characters provided in the third integer argument.
substring(CompanyName,1, 2) eq 'lf'
string tolower(string string)Returns a string that is the lowercase conversion of the string provided as the string argument
tolower(CompanyName) eq 'alfreds futterkiste'
string toupper(string string)Returns a string that is the uppercase conversion of the string provided as the string argument
tolower(CompanyName) eq 'alfreds futterkiste'
string trim(string string)Returns a string trimmed from spaces, based on the string provided as argument.
trim(CompanyName) eq 'Alfreds Futterkiste'
string concat(string string1, string string2)Returns a string that is the concatenation of the two string arguments provided.
concat(concat(City,', '), Country) eq 'Berlin, Germany'
int day(DateTime datetimeValue)Returns an integer that corresponds to the day of the datetime value provided as argument.
day(BirthDate) eq 8
int hour(DateTime datetimeValue)Returns an integer that corresponds to the hours of the datetime value provided as argument.
hour(BirthDate) eq 1
int minute(DateTime datetimeValue)Returns an integer that corresponds to the minutes of the datetime value provided as argument.
minute(BirthDate) eq 0
int month(DateTime datetimeValue)Returns an integer that corresponds to the month of the datetime value provided as argument.
month(BirthDate) eq 12
![Page 21: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/21.jpg)
Functions (3/3)Function Description Example
int second(DateTime datetimeValue)Returns an integer that corresponds to the seconds of the datetime value provided as argument.
second(BirthDate) eq 0
int year(DateTime datetimeValue)Returns an integer that corresponds to the year of the datetime value provided as argument.
year(BirthDate) eq 1948
double round(double doubleValue)Returns a double number that is the rounded value of the double value provided as argument.
round(Freight) eq 32
decimal round(decimal decimalValue)Returns a decimal number that is the rounded value of the decimal value provided as argument.
round(Freight) eq 32
double floor(double doubleValue)Returns a double number that is the floor value of the double value provided as argument.
floor(Freight) eq 32
decimal floor(decimal datetimeValue)Returns a decimal number that is the floor value of the decimal value provided as argument.
floor(Freight) eq 32
double ceiling(double doubleValue)Returns a double number that is the ceiling value of the double value provided as argument.
ceiling(Freight) eq 33
decimal ceiling(decimal datetimeValue)Returns a decimal number that is the ceiling value of the decimal value provided as argument.
ceiling(Freight) eq 33
bool IsOf(type value)Returns a boolean value stating if the target entity is of the type provided as argument.
isof('NorthwindModel.Order')
bool IsOf(expression value, type targetType)
Returns a boolean value stating if the expression provided as the first argument, is of the type provided as the second argument.
isof(ShipCountry,'Edm.String')
![Page 22: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/22.jpg)
DEMOQuerying data
![Page 23: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/23.jpg)
Sample Queryhttp://devbook.sp2013.local/_api/web/lists/GetByTitle(Documents')/RootFolder/Files?$expand=Author&$select=Name,Author,TimeLastModified&$orderby=TimeLastModified%20desc,Name&$skip=20&$top=10&$filter=substringof('Chapter',Name)%20eq%20true
Query Part Explanation
$expand=Author Expands the related object Author, while retrieving the documents.
$select=Name,Author,TimeLastModified Retrieves the fields Name, Author, and TimeLastModified.
$sort=TimeLastModified desc,Name Sorts the output descending by TimeLastModified, and ascending by Name.
$skip=20 Skips the first 20 items of the resultset (i.e. the first two pages of 10 items).
$top=10 Retrieves only the first 10 items of the resultset (i.e. the third page of 10 items).
$filter= substringof('Chapter',Name) eq true Retrieves only files with a file name that contains the literla "Chapter".
![Page 24: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/24.jpg)
Managing dataBecause life changes …
![Page 25: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/25.jpg)
How it works Leverages JSON requests
Plus some specific HTTP headers
Uses HTTP methods POST/PUT Plus X-Http-Method header
Be careful of cross-domain calls
![Page 26: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/26.jpg)
Common Rules HTTP header IF-MATCH with ETag value
Only for lists and list items ETag returned as HTTP header while querying data
Returned also in JSON/ATOM responses
HTTP header X-RequestDigest See next slide …
![Page 27: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/27.jpg)
User session validation Required X-RequestDigest HTTP header
Available as INPUT hidden: __REQUESTDIGEST jQuery: $("# __REQUESTDIGEST").val();
Available through: _api/ContextInfo JSON response includes: FormDigestValue
![Page 28: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/28.jpg)
Sample ContextInfo in JSON format{
"d": { "GetContextWebInformation": { "__metadata": { "type":"SP.ContextWebInformation" }, "FormDigestTimeoutSeconds":1800, "FormDigestValue":"0x8B48E76BAF6C86A17CCEC50F9A29E7CBB85816B883417C52C10C67 FB19760517B774CD71E43517635386DE585E92A0262779824E5E0C7ECA905436A048AC85AC, 08 Jan 2013 01:11:57 -0000", "LibraryVersion":"15.0.4420.1017", "SiteFullUrl":"http://devbook.sp2013.local", "SupportedSchemaVersions": { "results": [ "14.0.0.0", "15.0.0.0" ] }, "WebFullUrl":"http://devbook.sp2013.local" } }}
![Page 29: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/29.jpg)
DEMOEditing data
![Page 30: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/30.jpg)
Cross-domain callsCrossing the river …
![Page 31: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/31.jpg)
Cross-domain CSOM/JSOM calls from app web to host web
Are cross-domain calls app web site domain != host web site domain
Modern browser deny cross-domain calls We need to work around this … JSOM provides: SP.RequestExecutor
![Page 32: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/32.jpg)
App Web Host Web
SP.RequestExecutor.js
IFrame(AppWebProxy.ASP
X)
1) Download .js library
2) Emit IFrame
3) Download proxy page
4) Make REST/CSOM call
5) Get response data
6) Get data back to app
Cross-Domain Call Flow
![Page 33: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/33.jpg)
SP.RequestExecutor Arguments accepted
url: target URL method: HTTP method body: request body (JSON), optional headers: HTTP headers for the request
Accept, X-RequestDigest, X-HTTP-Method, IF-MATCH, etc. success: delegate in case of success error: delegate in case of failure
![Page 34: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/34.jpg)
SecurityLeaving in a safe world
![Page 35: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/35.jpg)
Authentication Techniques Anonymous
Read-only Require Use Remote
Interfaces permission
Windows integrated (NTLM, Kerberos)
OAuth
![Page 36: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/36.jpg)
OAuth Requires a context access token Provided in the Authorization header
Bearer + access token
jQuery.ajax({ url: "http://hostname/_api/contextinfo", type: "POST", headers: { "Authorization": "Bearer " + accessToken, "accept": "application/json;odata=verbose", "contentType": "text/xml" },})
![Page 37: Understanding the REST API of SharePoint 2013](https://reader036.vdocuments.us/reader036/viewer/2022062300/554f8e69b4c905435d8b4f3a/html5/thumbnails/37.jpg)
...and visit our sponsors who made this day possible!
Thank you!
Please rate this session...