TH3 Office 365 REST APIs. Peter Carson

TH3 Office 365 REST APIs

Peter Carson

Envision IT Services

• Focused exclusively on SharePoint

• Web Content Management –public web sites, Intranets, Extranets

Who needs an API?

• Custom Web Parts • Console Applications • Workflows

• PowerShell

• SharePoint Apps

How Are You Calling?

• C#

– On the SharePoint Server (Full trust code)

• Web Parts • Workflows • Console Apps

– Another Server (High Trust Apps)

• Provider Hosted Apps • Remote Event Receivers • Console Apps

• JavaScript

Full Trust Code

• Runs on the SharePoint Server

• Has access to the full server object model

• Traditional way SharePoint customizations were developed

• Not supported for Office 365

Calling from Outside SharePoint

• SOAP Web Services

– Supported back to MOSS 2007

– Difficult to work with, particularly through JavaScript

• Client Side Object Model (CSOM)

– Introduced in SharePoint 2010, expanded in 2013 – Libraries for C#, JavaScript, and Silverlight

• REST

– Introduced in SharePoint 2010, expanded in 2013

What is REST?

• Representational State Transfer

• Designed as an alternative to SOAP

– Simpler and easier to understand

• Architectural style, not a standard

HTTP Verbs

Verb Purpose

GET Read from SharePoint

POST Creates new objects

PUT Updates an existing object

Any properties not set explicitly are overwritten to their default values

MERGE Updates an existing objects

Preserves any existing properties not being set

Envision Shakespeare Company

• Reference project to demonstrate the features and capabilities of SharePoint 2013:

– Adaptive design for PC, tablet, and mobile

– Populated content including the complete works of Shakespeare – Extensive use of catalogs and content search web parts

– SharePoint search with refiners and preview – Image renditions, rotators, and galleries – Video support

– PowerShell build of full site

– Site columns, content types, and branding with adaptive design packaged in Visual Studio

Shakespeare Package

• All design files (MindMap, Axure Wireframes, Word specification, Adobe and HTML mockups) • Visual Studio 2012 solution

– Site columns and content types

– Branding (master page, page layouts, display templates, CSS, JavaScript)

– Term store navigation control

– Term store export/import tool with full support for 2013 navigation features

– Site content, including the complete works of Shakespeare tagged for the site

– PowerShell scripts for automated creation of the site, including site collection, features, and content

Retrieving List Data

• Top level site

– http://shakespeare.labvm12.envisionit.com

• Retrieve all lists

– http://shakespeare.labvm12.envisionit.com/_api/lists

• Get fields from a list by list GUID

–

http://shakespeare.labvm12.envisionit.com/_api/lists(guid'893525ab-6d50-425c-8858-c6294230aa75')/Fields

• Get list items from a list by Title

– http://shakespeare.labvm12.envisionit.com/_api/lists/GetByTitle('Ne

Turn off feed reading view

Data Format

• By default data is returned as XML

– Easy to consume in C#

• Alternatively you can specify JSON as the form

– JavaScript Object Notation

List REST Call

http://shakespeare.labvm12.envisionit.com/Pages/News-Rest-list.aspx

var url = _spPageContextInfo.webAbsoluteUrl + '/_api/lists/GetByTitle(\'News\')/items';

var deferred = $.ajax({ url: url,

method: "GET",

headers: { "accept": "application/json;odata=verbose", }, success: function (data) {

var results = data.d.results, $table = $('<table></table>');

$table.append('<tr><td>Title</td><td>Summary</td><td>Article Date</td></tr>'); $.each(results, function (i, item) {

$table.append('<tr><td>' + results[i].Title + '</td><td>' + results[i].ESCSummary + '</td><td>' + results[i].ArticleStartDate + '</td></tr>');

});

$('#RESTDemo').html($table); },

error: function (err) {

// handle error

alert('Error getting the News: ' + err); }

Search Driven Apps

• Read from the search index rather than directly from lists

• Can pull content from across multiple lists, sites, site collections, web applications, even farms

• News query for the browser

Search Rest Call

varnewsItems = [];

varurl = _spPageContextInfo.webAbsoluteUrl + '/_api/search/query?querytext='+

'%27(path:"'+ _spPageContextInfo.webAbsoluteUrl + '/lists/News") (IsDocument:"True" OR contentclass:"STS_ListItem")%27'+

'&selectproperties=%27Title,owsESCSummary,ArticleStartDateOWSDATE%27';

vardeferred = $.ajax({ url: url, method: "GET",

headers: { "accept": "application/json;odata=verbose", }, success: function(data) {

varresults = data.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results

for(vari = 0; i < results.length; i++) {

varfields = results[i].Cells.results;

vartitle = '', summary = '', articledate = null;

for(varj = 0; j < fields.length; j++) {

if(fields[j].Key == 'Title') title = fields[j].Value;

else if(fields[j].Key == 'owsESCSummary') summary = fields[j].Value;

else if(fields[j].Key == 'ArticleStartDateOWSDATE') articledate = fields[j].Value; }

newsItems.push({ 'Title': title, 'ESCSummary': summary, 'ArticleStartDate': articledate}); }

var$table = $('<table></table>');

$table.append('<tr><td>Title</td><td>Summary</td><td>Article Date</td></tr>'); $.each(newsItems, function(i, item) {

$table.append('<tr><td>'+ newsItems[i].Title + '</td><td>'+ newsItems[i].ESCSummary + '</td><td>'+ newsItems[i].ArticleStartDate + '</td></tr>'); });

$('#RESTDemo').html($table); },

error: function(err) {

// handle error

alert('Error getting the News: '+ err); }

Christie Medical Business Case

• Christie Digital is a World Leader in Visual Solutions for World-Class Organizations

• Christie Medical’s web site was a subsite of Christie

Digital, at www.christiedigital.com

Christie Medical Site Build

• Net new site build

• Completely independent site with its own URL and identity

• New branding and creative

• Built from the ground up to leverage SharePoint 2013 • Live at www.christiemed.com

CSWP Challenges

• CSWP is a very powerful web part

• Enterprise CAL only or E3/E4 in Office 365

– Not an issue on an anonymous site, full Enterprise features are included

• Limits results to a maximum of 50

– Paging is supported for going beyond this

REST Challenges

• By default the REST API is not available anonymously • Should only minimally relax security for it to work • Done through the queryparametertemplate.xml file

– Placed in a document library in the root site collection – Requires the farm, site, and web IDs, and what search

capabilities should be turned on anonymously

• Waldek Mastykarz (MVP) has an excellent post describing this

REST Implementation

var localSite = _spPageContextInfo.webAbsoluteUrl;

var url = localSite +

'/_api/search/query?querytext=' +

'%27(path:"' + localSite + '/lists/distributors") (IsDocument:"True" OR contentclass:"STS_ListItem")%27' +

'&selectproperties=%27Title,WorkAddressOWSMTXT,WorkCountryOWSTEXT,PrimaryNumberOW STEXT,LogoImageOWSIMGE,UrlOWSTEXT,LatitudeOWSNMBR,LongitudeOWSNMBR%27' +

'&QueryTemplatePropertiesUrl=%27spfile://webroot/queryparametertemplate.xml%27' +

Simcoe County District School Board

– 50,000 students

– Over 6,000 employees – Board office in Barrie

– Bordered by the Holland Marsh in the south, the

Simcoe County District School Board

• 119 schools and centres

– 87 elementary – 16 secondary – 6 learning centres – 10 alternative

• Each needs their own web site

– Being built on SharePoint 2013 – Elementary panel first

– Each has their own unique URL

– Content authored both at the school and centrally from the board

• www.scdsb.on.ca

– Pre-existing SharePoint 2010 site

Forest Hill Public School

• First pilot school

• Located in Midhurst, Ontario

• Local school content author training completed • Launch content loaded

• Going through final QA • Launch end of April 2014

Site Features

• Fully adaptive design

• SharePoint 2013 host named site collection

• Template makes it easy to bring up new school sites

• News and events can be targeted by the board to any number of school sites

– Target by panel, weather zone, trustee, language

– Presented in a blended view with the school news and events

• Home page rotator, links, hours, content pages all managed by the school staff

Events

• Fully adaptive calendar • REST search driven

Authentication

• Examples so far have been reading and displaying information

• Calls are coming from SharePoint hosted JavaScript • Security is less onerous

– APIs just need to make sure results are security trimmed

Posting

• When posting, you need to provide the form digest value

– Prevents replay attacks

• Your master page should have it

– <SharePoint:FormDigest runat=”server” />

• Time expiring, so refresh if you’re staying on one page for a long time

POST Sample

function addListItem(url, listname, metadata, success, failure) {

// Prepping our update

var item = $.extend({

"__metadata": { "type": getListItemType(listname) } }, metadata);

// Executing our add

$.ajax({

url: url + "/_api/web/lists/getbytitle('" + listname + "')/items", type: "POST",

contentType: "application/json;odata=verbose", data: JSON.stringify(item),

headers: {

"Accept": "application/json;odata=verbose", "X-RequestDigest": $("#__REQUESTDIGEST").val() },

success: function (data) {

success(data); // Returns the newly created list item information

},

error: function (data) { failure(data); }

DELETE Sample

function deleteListItem(url, listname, id, success, failure) {

// getting our item to delete, then executing a delete once it's been returned

getListItem(url, listname, id, function (data) { $.ajax({ url: data.d.__metadata.uri, type: "POST", headers: { "Accept": "application/json;odata=verbose", "X-Http-Method": "DELETE",

"X-RequestDigest": $("#__REQUESTDIGEST").val(),

"If-Match": data.d.__metadata.etag },

success: function (data) { success(data);

},

error: function (data) { failure(data); }

OAuth

• Standard way for apps to authenticate to web sites • Not just for SharePoint

– Facebook, Twitter

OAuth Authentication Process

Provider App _{Windows Azure AD}

Browse app No Token

User

Return page

REST call with Token Save Token in session Return JSON data

Redirect to SP Request Auth Code Redirect to App Return Auth Code

Request Access Token

High Trust Apps

• Server to server trust

• Uses digital certificates to establish a trust between the remote web application and SharePoint 2013

• Can only be installed to on premises SharePoint, not to Microsoft SharePoint Online

Common Consent Framework

• Enables web applications to access multiple workloads and resources across Office 365

– Can create web applications that access Microsoft OneDrive for Business files, SharePoint Lists, Exchange Calendars using Single-Sign On and an OAuth

Provider.

• Windows Azure Active Directory implements common consent

– All user accounts, application registrations, and permissions are stored in Windows Azure AD

– It implements the OAuth protocol for authorizing access from your web application to Office 365 resources

• Once your web application is registered in Windows Azure AD,

One Authentication to Office 365 APIs

Sign-On experience using Organizational Account

Basic Auth Protocol Flow with Office 365

App

AAD OAuth2 server Authorization/Token

Issuing endpoints

Office 365 Exchange API

endpoint

Use Code to get Exchange API Token

Token Response

Call API with Token Use refresh token to get

SharePoint API Token Token Response

Call API with Token Office 365 SharePoint API endpoint User Authorization Request

Graph API

• Part of Azure AD

• Provides a REST interface to query and update Window Azure AD (WAAD)

• Create and manage users, groups • Assign subscriptions for Office 365

Provider App Challenge

• No way to programmatically install apps on new sites and pages

• App model expects that a user will install and trust the app

Roll Your Own REST

• Visual Studio WebAPI

• Build your business logic on the server (but not on SharePoint)

– Field level security – Business rules

– Reading and writing from multiple data sources

• Create a REST interface for your client side code • Use Server to Server Trust to communicate with

Alternative Authentication Process with JWT

Provider App

Client Side Code Thinktecture

Browse app No JWT

Redirected to IP

User

Return JWT Security Token

Return page

REST call with Token

JWT

JWT

App trusts IP

Save Token in session

Frameworks

• Great open source community

• jQuery is a given when working with REST

• HandlebarJS is a templating engine for formatting the results

• KnockoutJS and AngularJS for building single page apps

Links

• Get started with the SharePoint 2013 REST service

• www.plusconsulting.com/blog/2013/05/crud-on-list-items-using-rest-services-jquery