TL;DR

Microsoft Graph API is a simple-but-powerful interface that allows developers to build rich applications to interact with a large number of Microsoft’s cloud-based services, including Office 365, OneDrive, SharePoint and many more. This is a significant benefit to for companies who have made the shift from on-premise to cloud-hosted software. Developers can now leverage a single API to build applications that interact with data across a variety of services. Read on for more details.

The Problem

Building applications that aggregate data from a variety of sources has always been a challenge for enterprises. This was especially true in cases where the respective systems did not provide friendly Application Programming Interfaces (APIs) for interacting with their data.

This problem is made to seem even worse in a world with nearly constant connectivity. Business users may find themselves thinking, “I have internet at home and on my mobile device – why can’t I view an Excel sheet from my SharePoint site at the office?”

Granted, we’ve had public-facing Web-based email and VPNs for many years now, but that only addresses a part of the issue – connectivity TO the systems. The other part of the issue is connectivity BETWEEN the systems.

The specific problem I was facing that led me to discover Microsoft Graph API was the need to interact with an Outlook mail account from within Dynamics 365 Customer Experience (CRM). Specifically, a CRM user creating a new Quote needed to send a Quote Report as a reply to an existing email conversation without bringing the email into CRM. (CRM Users that do not use the Outlook CRM Add-in will understand this pain.)

Getting Started

Once I discovered Microsoft Graph API, I realized that not only was this solution feasible, it was actually very straightforward for almost any developer. The Getting Started documentation guides you in the appropriate direction based on your needs and your development platform. Software Development Kits (SDKs) have been created to support all of the most popular platforms: Android, Angular, ASP.NET, iOS, Java, JavaScript, Node, PHP, Phython, Ruby, UWP, and Xamarin.

In my case, I was working in a web-based Single-Page Application, so I needed the JavaScript SDK. The documentation contains links to several sample applications on GitHub that demonstrate the entire solution, start-to-finish.

Potential Pitfalls

I discovered a few challenges along the way that I thought may be helpful to share.

• Authentication: Naturally, you’ll need to be authenticated with a Microsoft-supported account. If you aren’t assigned an account by your organization, you can visit https://account.microsoft.com to create a new account. I think they’re letting you use an existing email address these days (I use my Yahoo email address as my Microsoft account).
• Authorization: You’ll need to visit Microsoft’s Application Registration Portal to register the application that will be using the Microsoft Graph API. Each configured application will be assigned an App ID or Client ID. This value will generally be required as part of the authorization process when interacting with Microsoft Graph API. Don’t worry – the documentation provides step-by-step instructions for this process.
• Communication Workflow: This one can be a little bit tricky to understand. In my case of using the JavaScript SDK with a Single-Page Application, the communication workflow looks like this:
  1. User Authenticates with Microsoft’s Login, either with a popup window or by redirecting your application to Microsoft’s Login site.
  2. After successful login, a Login Token is provided.
  3. The Login Token is used to make yet another call to get an Access Token. The Access Token (which is a JWT) is then included with every interaction that is made with Microsoft Graph API.

Note: The included SDKs contain all of the necessary helper methods for these interactions. You can basically copy and paste the code from the sample applications to get a fully-working solution with very little effort.

It’s all REST and JSON

The mechanics of the interactions are based on REST, the de-facto standard of web-based APIs these days. And the data that is exchanged is all using JSON. Both of these technologies should be familiar with any web developer and are relatively simple for even new developers to master quickly.

For example, after being authorized, I can use the following URL to see the messages in my Inbox:

https://graph.microsoft.com/v1.0/me/messages

(If you are not authorized then you’ll only see an error message – I’ve intentionally left this link inactive to prevent showing an error message when clicking it here.) For an authorized user, a sample of the resulting data from the URL above will look something like this:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('48d31887-5fad-4d73-a9f5-3c356e68a038')/messages",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=12",
    "value": [
        {
            "@odata.etag": "W/\"CQAAABYAAAAiIsqMbYjsT5e/T7KzowPTAAEMTBu8\"",
            "id": "AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OABGAAAAAAAiQ8W967B7TKBjgx9rVEURBwAiIsqMbYjsT5e-T7KzowPTAAAAAAEMAAAiIsqMbYjsT5e-T7KzowPTAAEMOXaXAAA=",
            "createdDateTime": "2018-09-10T23:47:52Z",
            "lastModifiedDateTime": "2018-09-10T23:47:53Z",
            "changeKey": "CQAAABYAAAAiIsqMbYjsT5e/T7KzowPTAAEMTBu8",
            "categories": [],
            "receivedDateTime": "2018-09-10T23:47:53Z",
            "sentDateTime": "2018-09-10T23:47:53Z",
            "hasAttachments": false,
            "internetMessageId": "",
            "subject": "MyAnalytics | Your past week",
            "bodyPreview": "September 2–8, 2018\r\n\r\n\r\nHi Megan Bowen,\r\n\r\nMyAnalytics helps you spend your time on the people and things that matter.\r\n\r\n\r\n\r\n\r\nProtect time for your work\r\n\r\n\r\nMinimize unproductive collaboration\r\n\r\n\r\nStrengthen important relationships",
            "importance": "normal",
            "parentFolderId": "AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAuAAAAAAAiQ8W967B7TKBjgx9rVEURAQAiIsqMbYjsT5e-T7KzowPTAAAAAAEMAAA=",
            "conversationId": "AAQkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OAAQAM44kV7x1ZpNs2Lyjm8TUR4=",
            "isDeliveryReceiptRequested": false,
            "isReadReceiptRequested": false,
            "isRead": false,
            "isDraft": false,
            "webLink": "https://outlook.office365.com/owa/?ItemID=AAMkAGVmMDEzMTM4LTZmYWUtNDdkNC1hMDZiLTU1OGY5OTZhYmY4OABGAAAAAAAiQ8W967B7TKBjgx9rVEURBwAiIsqMbYjsT5e%2FT7KzowPTAAAAAAEMAAAiIsqMbYjsT5e%2FT7KzowPTAAEMOXaXAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "inferenceClassification": "other",
            "body": {
                "contentType": "html",
                "content": "[HTML EMAIL CONTENT - truncated for brevity]"
            },
            "sender": {
                "emailAddress": {
                    "name": "MyAnalytics",
                    "address": "no-reply@microsoft.com"
                }
            },
            "from": {
                "emailAddress": {
                    "name": "MyAnalytics",
                    "address": "no-reply@microsoft.com"
                }
            },
            "toRecipients": [
                {
                    "emailAddress": {
                        "name": "Megan Bowen",
                        "address": "MeganB@M365x214355.onmicrosoft.com"
                    }
                }
            ],
            "ccRecipients": [],
            "bccRecipients": [],
            "replyTo": [],
            "flag": {
                "flagStatus": "notFlagged"
            }
        }
	]
}

This will look familiar to anyone who has worked with JSON. Once this is consumed in your application, any of its values can be easily accessed.

Creating, updating or deleting data is similar, except that you must sometimes provide some JSON as part of the request. The documentation will always specify what is expected and the SDK provides the necessary structure so that it’s very understandable.

Next Steps

In addition to using the Getting Started documentation, you can try out any of the operations in a browser using the Graph Explorer. Finally, I found the reference documentation to be extremely helpful for everything from best practices to the specifics on each operation.

If you use Microsoft’s ecosystem and need to develop custom applications that interacts with data across multiple services, then using Microsoft Graph API will take your productivity to infinity and beyond!