The Microsoft Graph API is a set of services, published through a unique and consolidated REST endpoint, that allow users to consume the main functionalities and the most useful capabilities of the services offered by Microsoft Office 365. As you have seen in Chapter 1,
“Microsoft Office 365: A quick tour,” some of the main services offered by Office 365 are:
Microsoft Exchange Online Microsoft SharePoint Online Microsoft Skype for Business Microsoft OneDrive for Business Microsoft Video Portal
Microsoft Power BI
Microsoft Azure Active Directory
Many other services will become available in the near future, leveraging a common model of consumption and a shared set of development patterns that make it easier for developers to consume the entire Office 365 platform and provide business-level solutions fully integrated with Office 365.
From a low-level perspective, those services can be consumed from any development platform such as Microsoft .NET Framework, Java, PHP, JavaScript/jQuery, Node.js, and so on. The only requirement is the capability to make HTTP requests and to handle the JSON serialization to encode requests and decode responses.
From a high-level perspective, the Microsoft Graph API is a way to consume all the
services that were already available as a separate set of REST endpoints, through a unique set of rules and using a consolidated endpoint address. Chapter 4, “Azure Active Directory and security,” further explains why having a unique endpoint for the REST-based API makes the overall consumption easier and faster. For now, just consider that consolidation improves the code quality, performance, and usability of Microsoft Graph.
In Figure 3-1, you can see a schema of the overall architecture of the Microsoft Graph API.
FIGURE 3-1 A representation of the architectural schema of the Microsoft Graph API As you can see, the Microsoft Graph endpoint is a kind of wrapper on top of the APIs that were already available in Office 365 through the disparate Office 365 REST API, with the addition of some new API and the Office Graph insights and relationships. So far, the main services offered by the Microsoft Graph API are:
Users and Groups, which are services related to users’ information, groups’ definitions, and groups’ membership. These services will be covered in depth in Chapter 6, “Users and Groups services.”
Files, which target the OneDrive for Business service and will be explained in Chapter 7, “File services.”
Mail, calendar, and contacts, which are services related to the Exchange Online service and will be covered in depth in Chapter 5, “Mail, calendar and contact services.”
The authentication and authorization layer is provided by Microsoft Azure Active
Directory (Azure AD), and from a development perspective you will be able to implement a client wrapper within whatever development platform you choose, including Microsoft .NET, iOS, and Android.
From a URL perspective, the unified approach the Microsoft Graph API supports and sponsors allows you to consume all the services from a basic unique URL, which is
https://graph.microsoft.com. To consume a specific API or service, you will have to append to the base URL the version number of the API that you want to consume and the name of the target API. For example, if you want to consume version 1.0 of the Microsoft Graph, the URL will be like the following:
http://graph.microsoft.com/v1.0/<service-specific-endpoint>
If you want to consume the beta version of the Microsoft Graph, you can substitute the v1.0 version number with the beta keyword, using a URL like the following:
http://graph.microsoft.com/beta/<service-specific-endpoint>
In general, for any existing or future version of the API, the URL to consume it will be like the following:
http://graph.microsoft.com/<version>/<service-specific-endpoint>
Microsoft is also working on some open source SDK projects hosted on GitHub that allow you to consume the Microsoft Graph easily from custom developed solutions. These open source SDK projects can be accessed through the following URL:
http://graph.microsoft.io/code-samples-and-sdks
In particular, if you want to consume the Microsoft Graph API from a Microsoft .NET software solution, you can leverage the Microsoft Graph SDK library for .NET, which is available as a NuGet package in Microsoft Visual Studio. The name of the NuGet package is Microsoft.Graph. In Chapter 8, “Microsoft Graph SDK for .NET,” you will learn how to use this SDK in your solutions.
On GitHub, under the MicrosoftGraph main organization that is available at the URL
https://github.com/MicrosoftGraph/, there are samples of how to use the Microsoft Graph API within iOS (https://github.com/microsoftgraph/msgraph-sdk-ios) and Android
(https://github.com/microsoftgraph/msgraph-sdk-android).
In general, if you want to leverage the Microsoft Graph API from any platform, you can always use the REST API directly via HTTP. You can also consider using the VIPR tool (https://github.com/microsoft/vipr), which is a toolkit for generating client libraries for any OData service. The VIPR tool supports C#, Objective-C, and Java. Internally, the Microsoft Graph SDKs use the VIPR tool.
You can even use the Office 365 REST API; however, is not unified under a unique and common endpoint URL. The old development model already has client libraries targeting the main and most-adopted development platforms like Microsoft .NET, JavaScript, and some Open Source SDKs for Android and iOS. In particular, there is a .NET client library that is still available on NuGet to consume the Office 365 REST API easily with Microsoft Visual Studio and the Microsoft Office development tools for Visual Studio. This client library
allows you to leverage the Office 365 REST API within a wide range of Microsoft .NET custom software solutions. The supported flavors of .NET software solutions that can leverage the .NET client library for the Office 365 REST API are:
.NET Windows Store apps Windows Forms applications WPF applications
ASP.NET MVC web applications ASP.NET Web Forms applications Xamarin Android and iOS applications Multidevice hybrid apps
In this chapter, you will focus on the Microsoft Graph API, and in the following chapters, you will see how to leverage it within Microsoft .NET Framework. From a technology choice perspective, you should use the new Microsoft Graph API as much as you can and avoid using the per-service REST API.
In the following sections, you will find many more details about the main and most relevant Microsoft Graph services. To properly consume them, you will have to leverage an HTTP and REST client tool. Microsoft, for testing and development purposes, provides a tool with a web-based UI that is called Graph Explorer. It is available at the following URL:
https://graph.microsoft.io/en-us/graph-explorer
In Figure 3-2, you can see a screenshot of the UI of the Graph Explorer application. To use the Graph Explorer, you have to sign in, clicking the button in the upper-right corner of the welcome screen and providing your Office 365 tenant credentials. Then, you will be able to query (HTTP GET/POST/PATCH/DELETE) the services using a friendly web-based UI. The Graph Explorer will handle all the security plumbing required to query the target tenant via REST API.
FIGURE 3-2 The sample Graph Explorer app in action
Another useful tool for testing any REST API is Fiddler, which is a free tool made available by Telerik. It can be downloaded from the following URL:
http://www.telerik.com/fiddler