Building Solutions with Graph

Purvin Desai Cloud and SharePoint Architect Follow @purvd Building solutions with Microsoft Graph

TABLE OF CONTENTS

Introduction ...... 1

What is Microsoft Graph? ...... 1

service Architecture ...... 1

Microsoft Graph API metadata ...... 4

TraveRsing the graph ...... 4

Graph Explorer ...... 5

Microsoft Graph SDKs ...... 5

Paging Capabilities ...... 5

Service Exceptions & Throttling ...... 5

CRUD Capabilities ...... 6

Notifications ...... 6

Type Extensions ...... 6

Summary ...... 7

Explore ...... 7

Building solutions with Microsoft Graph

INTRODUCTION

Note: Microsoft Graph has two endpoints: V1.0 and beta. Some of the content in the document refer to beta endpoint, and it is not recommended to build production code with beta endpoints.

WHAT IS MICROSOFT GRAPH?

Microsoft Graph (previously called Office 365 unified API) is a unified API endpoint, based on advanced machine learning algorithms which are fed by data and user behavior and intelligently makes connections between siloed entities.

This unified API (https://graph.microsoft.com) aggregates data from multiple Microsoft cloud services like Outlook, OneDrive, Azure Active Directory, OneNote, Office Graph, etc. This API has full CRUD capabilities and in addition provides mechanisms for subscribing to notifications. It also allows extending existing entities with certain types. Microsoft Graph provides deep insights, analytics and relationships between various entities.

Prior to Microsoft Graph, in order to work with these services, you would have to make calls to different endpoints of the respective services. It required complex authentication flows in order to communicate with multiple services from with a single application. With unified API, one can work with multiple services with a single authentication token.

Microsoft Graph is a complete solution that takes advantage of wealth of information available in an enterprise or in public cloud. This document documents various aspects of Microsoft Graph and how it they can used to build amazing experiences that will delight users and help us to be more productive.

SERVICE ARCHITECTURE

Fig. Service Arcitecture (ref: https://graph.microsoft.io)

1

Building solutions with Microsoft Graph

OFFICE GRAPH

Office 365 is Microsoft’s cloud platform for the enterprise and the consumers. It’s a suite of services ranging from Email, Exchange Online, document storage in OneDrive for Business and content management in SharePoint. It even includes Word, Excel and PowerPoint running on client machines or in your browser. Inside Office 365, there is a wealth of data and relationships, that we store in what we call the Office Graph. The Office Graph is an intelligent fabric that combines machine learning to match the connections between people, content and interactions all across Office 365.

Traditionally, we’ve had silos in the enterprise software, having loose connections between documents, users, emails, discussions, etc. Office Graph connects these entities together and organize them across your work. Office Graph then becomes a layer across Outlook, , One Drive for Business, etc. Office Graph simply connects these dots in the enterprise across the workloads. Office Graphs adds semantics and insights to the relationships making these things available to all the tools in Office 365 as well as any app that you create.

SECURITY AND PRIVACY

Office Graph respects security for whatever data source data comes from. You will never see anything in the Office Graph that you cannot see in the original system. You can see graph as a huge network where every user sees his part of the graph and is security-trimmed for that particular user.

Some user actions and some relations are private and available only to the current user. Those actions may be aggregated in anonymous manner. For e.g. it shows a number of views on a particular document, but won’t show exactly which users. Authorship or editing a document is a public action, whereas viewing is private action.

MICROSOFT GRAPH – UNIFIED API – HTTPS://GRAPH.MICROSOFT.COM

This is an API on top of all other APIs, giving developers one coherent interface, one way of authenticating. In the past, you would have to use different authentication methods towards SharePoint, Outlook, etc. With unified API you can use one endpoint for all queries, which exposes data on REST.

This is a strongly typed API. If you are dealing with a User, you are dealing with a User. If you are dealing with a Document, you are dealing with a Document. This allows different applications to work with a well-defined data model and a consistent way of working.

MODELING CONCEPTS

The modeling concepts in the Office Graph starts with a node. A node represents some entity with a stable ID, such as a user or document. The node has properties and navigation properties. A navigation property is an edge or pointer to another node. It has a type but no properties.

A node may have multiple extensions (or views), each with a different set of properties describing some other aspect of the entity.

We also have a special type of nodes as we call Action nodes. An action node has some properties that describe the action taken as well as the action and the object or object(s) in question. It can also have additional properties an edges that give more context such as the app used to take the action and similar.

The Office Graph also can contain Relationship nodes. This how n-ary relationships and relationships with properties are represented.

2

Building solutions with Microsoft Graph

Let’s say there are two nodes, a User and a File. These nodes are entities in the Graph. These nodes have a set of properties. So a User node could have a Name and an Alias and other properties as well. A file could have a Title, URL and an Author. In this case, Author is a navigation property. It’s a property that refers to another node, which is a User. Thus, it’s a pointer in the Graph. And when you look at any node in the Graph, that node could have multiple aspects or extensions. For e.g. a User can also be an Employee.

Then we have action nodes, which then represents actions taken by User, and a typical action node will be TimeStamp, when this action was done, which User performed the action and what object the action was performed on. In addition, there will be a number of textual information as well, such as which action the User performed. https://msdn.microsoft.com/en-us/office/office365/howto/query-Office-graph-using-gql-with-search-rest-api

REST AND ODATA

Microsoft Graph API (https://graph.microsoft.com) provides programmatic access to Office 365 through an REST API endpoint, that support a wide range of OData operators.

If you have experience consuming REST services and have a developer platform which allows you to make HTTPS requests, with open authorization tokens in request header, you can call Exchange Online, One Drive for Business and other services provided through Office 365 offering. https://graph.microsoft.com is the main URL for the entire family of Microsoft services. It can be used to interact with One Drive for Business, mailboxes, calendar, people, search, Office Graph, etc. from whatever device and platform you like. The API is consistent across multiple services and platforms.

Following HTTP verbs or methods are permitted on the resource, to access and manipulate them. These correspond to create, read, update and delete (or CRUD).

POST, GET, PUT, PATCH, and DELETE

HTTP Verb CRUD Success Response Example

POST Create Status Code: 201. Create a domain. Returns newly created object.

GET Read Status Code: 200. Get domains Returns requested resource.

PUT Update/Replace Status Code: 204 Assign a contact’s manager No response body is returned.

PATCH Update/Modify Status Code: 204 Reset a user's password No response body is returned.

DELETE Delete Status Code: 204. Delete a user

No content.

3

Building solutions with Microsoft Graph

All Microsoft Graph API requests use the following basic URL pattern:

https://graph.microsoft.com/{version}/{resource}?[odata_query_parameters]

For this URL:

 https://graph.microsoft.com is the Microsoft Graph API endpoint  {version} is the target service version, for example, v1.0 or beta.  {resource} is resource segment or path, such as o users, groups, devices, organization o The alias me, which resolves to the signed-in user o The resources belonging to a user, such as me/events, me/drive or me/messages o The alias myOrganization, which resolves to the tenant of the organization signed-in user  [odata_query_parameters] represents additional OData query parameters such as $filter, $select, $orderby, $expand, etc.

Additionally, you can specify the tenant as part of your request, which is optional and not required.

MICROSOFT GRAPH API METADATA

The service document ($metadata) is published at the service root. For example, you can view the service document for the v1.0 and beta versions via the following URLs.

Microsoft Graph API v1.0 metadata:

https://graph.microsoft.com/v1.0/$metadata

Microsoft Graph API beta metadata:

https://graph.microsoft.com/beta/$metadata

The metadata allows you to see entities, entity types and sets, complex types and enums of the Microsoft Graph REST API. Using the metadata and readily available third-party tools, you can create serialized objects and generate client libraries for simplified use of the REST API.

A resource URL is determined by the Microsoft Graph entity data model. The prescription is outlined in the entity metadata schema ($metadata).

The path URL resource names, query parameters, and action parameters and values are case insensitive. However, values you assign, entity IDs, and other base64 encoded values are case sensitive.

TRAVERSING THE GRAPH

If you think of a Graph where you have some relationships from Users to Entities that are popular with colleagues and with whom the User interacts frequently. You can navigate a User to look at everything that is trendingAround this user using this URL:

GET /users(‘[email protected]’)/trendingAround

For the list of users that a user has been working with:

GET /users(‘[email protected]’)/workingWith

For the list of users reporting to a manager:

4

Building solutions with Microsoft Graph

GET /users(‘[email protected]’)/directReports

GRAPH EXPLORER

The Graph Explorer Tool available here: https://graph.microsoft.io/en-us/graph-explorer, allows you query all graph APIs after you sign in to your tenant. The Graph Explorer app will request a bunch of permissions to your tenant, so that it can successfully execute all queries.

It provides a way to execute v1.0 as well as beta(preview) endpoints, and maintains a history of the requests made. You receive a JSON response to your calls and view the response headers too.

This is a great tool to explore Graph APIs and see it in action.

MICROSOFT GRAPH SDKS

Microsoft Graph SDKs (https://graph.microsoft.io/en-us/code-samples-and-sdks) are available on Github. It is an open source SDK and can be extended by you. Graph SDKs allow you to consume Graph APIs from various platforms. It is currently available for .Net, iOS, Android, JavaScript, PHP, Python, Ruby, AngularJS platforms.

Graph SDK is a bunch of main types defined by developers who created the Graph API. There are also auto- generated types, created by an open source engine VIPR (https://github.com/Microsoft/Vipr) using $metadata descriptors.

Graph SDK supports open authentication models via Azure AD Authentication Libraries (ADAL) and MSAL (Microsoft Authentication Library - Preview). You need to register your application either with Azure AD (https://portal.azure.com) or the new Application Registration Portal (https://apps.dev.microsoft.com – Azure AD v2.0 - Preview). The Application Registration Portal allows to authenticate enterprise Azure AD identities (work or school) along with personal Microsoft identities (live.com or outlook.com). In addition, Azure AD v2.0 endpoint allows dynamic permission requests during app runtime and incremental consent requests.

It is asynchronous by design, which helps to create responsive applications from whichever platform you are working with, and helps build smart behaviors. https://graph.microsoft.io/en-us/changelog is a good place to keep track of newly released APIs for v1.0 and Beta versions.

PAGING CAPABILITIES

The Graph API supports paging capability to ensure data can be managed in chunks, instead of receiving the entire collection at once. You can include a skip token ($skiptoken) to requests that will allow you to get next page of results. This skip token can be combined with a previous-page=true query argument to page backward.

The Graph SDKs too provide high level support for paging via NextPageRequest property.

SERVICE EXCEPTIONS & THROTTLING

The SDK provides specific service exceptions against the calls made to the Graph API, so that the exceptions can be properly handled. Through the ServiceException object, we have access to the error details that were sent by the server. The ServiceException type provides an IsMatch() method which allows to verify if the current exception is of any of the predefined error type provided by the API.

5

Building solutions with Microsoft Graph

One interesting error type is the throttling exception. Your API calls to the server may be throttled if they violate certain predetermined rules. A specific ServiceException will be thrown in that case, would allow you to verify with the IsMatch method. You will need to wait for some time before retrying the same API call to the server, so that the platform is not stressed.

CRUD CAPABILITIES

It is important to realize that the Graph API provides full CRUD (Create, Read, Update and Delete) capabilities. Following are some examples:

To read all calendar events:

GET https://graph.microsoft.com/v1.0/me/events

To create a new calendar event:

POST https://graph.microsoft.com/v1.0/me/events

To modify an existing event:

PATCH https://graph.microsoft.com/v1.0/me/events/{event-id}

To delete an existing event:

DELETE https://graph.microsoft.com/v1.0/events/{event-id}

NOTIFICATIONS

The Microsoft Graph REST API delivers notifications to clients using a mechanism called WebHooks. A client needs to subscribe and configure it’s URL to receive notifications. Client applications can use notifications to update their state upon changes on the server.

When an event occurs with one of the subscribed resources, the subscriber is notified. Subscriptions have an expiry and applications should renew their subscriptions before they expire. They can also be unsubscribed.

Notifications are asynchronous in nature and an app can subscribe to one of the following resources: Messages, events, contacts, group conversations and drive root items.

Client applications will need to build a mechanism to process the incoming notifications.

TYPE EXTENSIONS

Microsoft Graph API nodes can have multiple extensions. This is powerful, because you can take existing data and you can add more sets of properties to it with these extensions. For e.g. a User can be extended and defined as an Employee and you can define what properties an Employee should have. Another example could be a File, which could be extended to either a Document or a Video.

When you the Graph, you can examine the sort of extensions the nodes have. You can check if a User is also an Employee. You can ask only for Employees to be returned.

6

Building solutions with Microsoft Graph

Currently, Graph allows data extensions for a message, event or contact in the signed-in user’s mailbox, or in an event in a group calendar of an organization. It is represented by the openTypeExtension resource and is an OData v4 open type. This resource has the additional extensionName property.

SUMMARY

Microsoft Graph derives insights and intelligence in your organization work, making it easier to keep up to date with what’s going on in the organization, easier to find data and discover new connections and learn about people in the organization.

Microsoft Graph will continue to evolve allowing not just to query the graph, but to add your own content and even define the kind of content that goes into the graph. With these extensions, great applications and solutions can be built with remarkable experiences.

EXPLORE

Read about Microsoft Graph: https://graph.microsoft.io/en-us/docs

Explore Graph APIs: https://graph.microsoft.io/en-us/graph-explorer

Build Applications: https://graph.microsoft.io/en-us/code-samples-and-sdks

7

Join the European SharePoint Community by following us:

BLOG

For more FREE SharePoint & Office 365 content such as webinars, presentations, eBooks, videos & more check out our Resource Centre

To visit the Resource Centre please click HERE.