One API to access all of your data in the Microsoft Cloud? We’re remarkably close to that reality. Here’s what you need to know to start building applications with the Microsoft Graph API.
The Microsoft Graph is evolving into a service that provides direct API access to user information, documents, business intelligence (BI) and machine learning insights based on data from the company’s cloud-based applications and data services. While only 18 months old, Graph benefits from years of incremental work by Microsoft on Office-based data interchange features and a broad, mature platform of cloud services on which to build.
Graph’s primary benefits, however, grow from two important features: significant sources of cloud-based data and a consistent, flexible API that’s rapidly gaining new services
First, Graph enables you to access, combine, and build workflows and applications with data across a broad range of Microsoft Cloud services, including Azure Active Directory (Azure AD), Intune, Office 365, OneDrive, Power BI, SharePoint, OneDrive and more. The data may be provided by employees using Microsoft Cloud services within your organization, it could be customer information generated through business processes and applications, or it could even be provided by third-party application services.
Second, Graph provides a broad, straightforward, and consistent set of API endpoints for accessing your cloud-based data and machine learning insights. Previous data interchange efforts provided access to limited data (such as just SharePoint or Exchange data, or just data for a particular business service, such as search, scheduling, or advertising). API access was often provided through language-specific libraries or complicated data-access interfaces. Refreshingly, Graph uses simple HTTP-based API endpoints that you can access through the language or application framework of your choosing.
There’s been a lot of talk about the high-level collaboration and BI scenarios that Microsoft can, potentially, enable through the Graph API. However, there’s been significantly less explanation of the actual interfaces presented for your team to develop against and the resources Microsoft has made available for you to employ these interfaces in your own applications or daily workflows.
I’m going to walk you through the specifics of what Graph enables developers and IT professionals to do today, along with the tools and resources Microsoft has released so far for building Graph-based applications.
But first, let’s step back for a minute and briefly look at where Graph came from and what it proposes as a solution today.
What Is Microsoft Graph?
Microsoft has a long history of ambitious data interchange concepts that it iterates forward generation by generation. The original Microsoft Graph (also known as Microsoft Chart) was a 1990s-era Object Linking and Embedding (OLE) technology for Office apps, specifically Access and Excel. And it’s worth pointing out that OLE itself was an evolutionary step from the Dynamic Data Exchange (DDE) interprocess communication mechanism introduced in the late 1980s.
Jumping forward a decade or so, Microsoft continued to ship interesting cross-application collaboration tools such as Groove Networks, the company founded by Ray Ozzie that Microsoft acquired in 2005. The Groove technology evolved into the SharePoint Workspace and Azure AD, and in March 2014 Microsoft launched the Office Graph, consisting of two social networking technologies and a new search and discovery app, code-named “Oslo,” plus a new “Groups” capability, which Microsoft started extending across Office. In November 2015, the Office Graph became Microsoft Graph, a sweeping effort to bring BI beyond Office to its connected frameworks. Microsoft started out by rolling much of the Azure AD feature set into Graph.
Here’s where the technology has finally caught up with Microsoft’s ambitions: If you’re using Microsoft’s cloud services and applications, the Graph API lets you access all of that information, create service workflows, and operate on user information, documents, and machine learning insights from that data. Microsoft is closer than ever to offering a single API to build data-interchange and machine learning applications on all of the data from all of its cloud-based applications. Maybe not all just yet, but more than we’ve seen so far.
In this case, “graph” refers not to the concept of a graph database — it may in fact use a graph database behind the scenes, though Microsoft has not discussed the underlying data structures used — but more important, I think, it refers to the concept of a social graph for your documents, data and contacts within the Microsoft Cloud.
To turn this around and look at it from a user’s perspective, people in your organization are using a variety of Microsoft applications and services, including Azure AD, Office 365, OneDrive, OneNote, SharePoint, Planner, Intune and more. Graph gives you the opportunity to access and analyze all of that data through a single, consistent API layer that is straightforward to address and simple to use.
The Graph API enables some fairly interesting cross-application scenarios right out of the box. Show me the documents used by the people I work with most often. Tell me when people are added to AD and automatically kick off employee onboarding workflows. Users, groups, e-mail, contacts, and tasks are all available directly through the Graph API endpoints, along with files, notes, and chat conversations (see Figure 1).
Using the Microsoft Graph APIs
Using the Graph API to access data is straightforward and remarkably transparent for developers who have any experience using Web service APIs. Microsoft chose to build Graph by employing mainstream, easy-to-use technologies: OpenID Connect and OAuth 2.0 for authentication to the service (using Azure AD as your identity provider), HTTP-based REST API endpoints, and standard JSON-formatted response objects.
Common data types and tasks are organized through individual API endpoints, which you’ll recognize as HTTP URLs. For example, the https://graph.microsoft.com/v1.0/me endpoint provides information about the authenticated user. Further information about that user is provided by child API endpoints: my Outlook e-mail (/me/messages), my calendar (/me/calendar), my OneDrive files (/me/drive/root/children).
Say I wanted to know about my provisioned software. The API endpoint for this Microsoft Graph data is: https://graph.microsoft.com/v1.0/me/provisionedPlans
Along with some system information, the response includes an array of objects that specifies which software has been provisioned for my use, as shown in Figure 2.