In-Depth

Microsoft Graph 101: Build Intelligence with Microsoft Graph

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.

• By Terrence Dorsey
• 06/05/2017

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.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(
    'b63d5fb9-4f43-44c4-8f9d-fd0727842876’)/
    provisionedPlans",
    "value": [
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "SharePoint"
      },
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "SharePoint"
      },
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "CRM"
      },
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "MicrosoftCommunicationsOnline"
      },
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "exchange"
      },
      {
        "capabilityStatus": "Enabled",
        "provisioningStatus": "Success",
        "service": "MicrosoftOffice"
      }
    ]
}

As you can see in Figure 2, the user account here has access to SharePoint, CRM, messaging with Office Communicator or Skype for Business (and Lync), Exchange e-mail, and Office 365.

Many of the examples you’ll see use simple HTTP GET requests to return current information, but you can also submit POST requests, such as assigning licenses to a user, or DELETE requests, such as deleting OneDrive files.

Delta query, a Graph feature currently in preview, enables you to get only changes that occur to your cloud data or related insights between requests. Graph keeps track of all relevant changes since your last query. When you send another delta query, the API returns either updated data since your last request or, if there aren’t additional changes to show, a new deltaLink URL to use for your next request. For push-style notifications, Graph also supports Webhooks-based Subscriptions.

These kinds of data insight-driven responses make it easy to kick off workflows in response to business events without requiring that your application track the underlying data for changes.

Online you’ll find an excellent collection of Graph documentation, which also covers beta endpoints and features, along with an interactive Graph Explorer that lets you experiment with API calls and see the responses (see Figure 3). The Quick Start walks you through all of the steps necessary to call the Graph API, from choosing the API endpoint and development platform, to registering your application and generating authentication keys.

More Graph Development Resources
Another thing Microsoft has done well with the rollout of Graph is providing API wrappers (SDKs in Microsoft parlance) and code samples for a wide variety of programming languages and development platforms. For desktop and general-purpose development there are SDKs for the .NET Framework (including Windows Phone 8.1 and higher), Python and Ruby. For Web development Microsoft provides SDKs for AngularJS, ASP.NET MVC, JavaScript, Node.js, PHP and TypeScript. For mobile development, there are SDKs for Android (Java), iOS (Objective C and Swift) and Xamarin (C#), in addition to the .NET Framework SDK.

The SDKs, along with code samples for all supported languages and platforms, are available on the Graph Samples & SDKs page or directly from the Microsoft Graph GitHub repositories. Microsoft Graph Client Library packages are also available through the NuGet Gallery, and there’s a Microsoft Graph API module in the Windows PowerShell Gallery.

This may seem like a lot of resources to sort through, but the variety of development options and related sample code is a good thing. Your team can choose the development path best suited to your skills, environment and business needs. PowerShell, Python or Ruby might be well-suited to one-off scripts, DevOps teams, and other in-house tasks, while the .NET Framework and mobile SDKs may be better suited for full-scale application development. Fortunately, you have a lot of options, which is great.

Graph Cloud Service API Advantages
There are several advantages the Graph cloud service-based approach brings to any solutions you might build with it.

First, if you’re using Microsoft’s cloud-based applications, Graph gives broad access to data and insights across all of the product offerings. Just in the last 18 months Microsoft has expanded the breadth of Graph data access from Office 365 to include OneDrive, OneNote, Power BI, Azure AD and, most recently, Intune.

Second, Graph offers consistent API endpoints across all supported product offerings. You don’t need to learn new SDKs or APIs when building applications for different products or data types.

Third, as a cloud service, Microsoft can continually release new Graph API endpoints, machine learning capabilities and support for additional products without requiring updates in your existing Graph-based applications. Updates are completely non-disruptive and available as soon as Microsoft rolls them out -- no downloads or installations required.

Finally, Graph API is available to any user or service that can reach the Microsoft Cloud, on-premises or in the field. If you have access, your application can use the Graph APIs.

Keeping Tabs on Graph
Aside from the breadth of APIs and SDKs, perhaps the most interesting aspect of Graph is how quickly Microsoft is expanding the API endpoints and service coverage. The Intune APIs for Graph were added in January 2017 and have expanded every month since then (with dozens of additions in March and April alone). Microsoft also added a new Planner API in April.

The best way to keep up-to-date on details as the Graph API grows and matures is to check the Changelog for Microsoft Graph, which provides monthly release notes with links to documentation for changed or new features. The Office Dev Center Blog offers higher-level notes on Graph features, and you should also follow the Enterprise Mobility and Security Blog for details on Graph API endpoints related to Intune.

For developers, it would be smart to follow the issues and pull requests on GitHub for any SDKs or examples incorporated into your projects.