Home
/
Blog
/
Ultimate Tutorial about Microsoft Graph APIs

Ultimate Tutorial about Microsoft Graph APIs

What is Microsoft Graph

In this article, we’ll talk about Microsoft Graph APIs and will show you a quick preview of the essential features. This technology is growing up too fast so some existing features may not be longer available at the time of reading and surely new features will be added to it after the time of writing.

Microsoft Graph API – formerly known as Office 365 unified API – is the new service-oriented architecture owned by Microsoft to allow developers to access a vast amount of data from the Microsoft cloud platforms. Microsoft web API is essentially designed to collaborate with Office 365 and some other services hosted on the MS Azure cloud platform.

Microsoft API and service architecture

The Microsoft Graph APIs expose RESTful services. This makes it very flexible because REST is compatible with almost any modern platform programming language. The exchange format is essentially in JSON and it can be encapsulated into the HTTPS transport security. The central point of Microsoft Graph is the concept of User, the authentication and authorization follow the OAuth2.0 mechanism making the user and role management to be standard for developers.

Microsoft Graph API revision

At the time of writing, Microsoft Graph API v1.0 is a stable revision that fulfills all production qualifications. A beta revision is also available in parallel for the latest releases, however, its main purpose is for testing new functionalities by the early adopter, and in any way, it is not recommended to be deployed into the production environment.

What are the technical skills requirements to get started with Microsoft Graph API?

As stated earlier Microsoft Graph API is using RESTful services. You need to have first a basic background about how REST is working. The next is to have a good grasp on how to build queries using REST sauce. This part is pretty the same thing as doing ADO.NET services queries. And last but not least one is to know the REST resource URL. For example, if you want to retrieve all the contacts for a given user, you should be aware of the exact resource URL matching your expectation. You may be noticed that those requirements remain valid regardless of any programming languages. After the server return back to your apps, you need to write some codes in your favorite languages to parse JSON format in order to extract entities you may need to use. This is how it works at a basic level.

Microsoft, fortunately, provides language-specific SDK to communicate with Microsoft Graph in the test of object-oriented programming. If you’re going on that way, the SDK is managing automatically the whole process. Thus you’re not going to deal with basic HTTP requests, instead, you’re dealing directly with the platform object representation. The following technologies have a good integration within Microsoft Graph: ASP .NET MVC, Universal Windows platform, Php, Angular, Node.js, Ruby, and for mobile platforms Android, iOS Swift, iOS Objective-C, and Xamarin. We will show you a code snippet later on.

Easy testing

From the beginning as his being, Microsoft always took care of developer’s life and this time Microsoft provides them with a very helpful online utility name Graph Explorer to allow them to test their REST queries in the easiest way that ever existed. You can experiment with your own data on the cloud. The principle is done in 2 steps: sign in with your Microsoft Account, create your app credentials and secrets then run any queries you want in the URL query bar. It is available at https://developer.microsoft.com/en-us/graph/graph-explorer

Before accessing the services – setting up account credentials

From your Microsoft account (for example outlook.com ) you need to get an appID and secret from the Microsoft Application Registration portal. The appID and secret are used to identify your profile each time a request is made by the Microsoft Graph API. If you are familiar with Facebook / Twitter / Linkedin / Google plus Application development the same mechanism is used here to access remote resources. If you omit this step or give a wrong AppID/secret the service will throw a notification with the corresponding error message.

What can a developer do with Microsoft Graph API?

Microsoft Graph API allows developers to build rich apps using a variety of data sources. Under the hood, it is more than a simple tool to access cloud storage. Microsoft Graph indeed comes with high-level interfaces and endpoints to perform business intelligence data analysis. This feature is very helpful if you are rowing in machine learning analysis or in a need of high-quality level reports and dashboard plots. It comes with a bunch of insights algorithms for mining predictions and forecast purposes.

We enumerate below the essential components of Microsoft Graph that can be accessed using the API:

Mail services (outlook account) and Exchange server: if you plan to send emails or more generally communicate with the mail server. As a developer you can drive email service flows from your apps without any knowledge of how to configure Exchange server. You can even send an email on behalf of another user.
Calendar for managing schedules and events. Your app can now automatically manage your incoming events by simply calling the calendar and events API. You can add, delete, or modify your schedule dashboard by your favorite programming language.
Documents Management System for documents flows, track and share Office365 documents like wordbooks, Excel sheets, etc. Microsoft Graph API gives your app the advantage of editing an excel file referenced on the cloud without having to open it in an Excel program. You can locate an excel worksheet cell or you can add a chart image directly from your code.
Tasks and workflows between stakeholders by Office 365 Planner API, you define a task first, then add users going to participate in the task, and finally, run the workflow. Depending on the type of workflow, a user may approve his task before it continues to the next user or rejects it to send it back for review to the previous user. The API is also able to show the task progress by giving the percentage of the completed task.
File and media transfers through Microsoft One Drive storage or Sharepoint document library, you can exchange photos, videos, streams, and many other formats. Ready-made API already exists to handle all of them. You can even call the Apis outside your current domain using the Cors capabilities. This particularity is the way to share everything everywhere (of course you always have full control over what you want to share and who had access to them)
Messages and conversations between people or network groups. This feature allows developers to build powerful apps especially mobile apps to connect people and allow them to communicate in real-time wherever they are. A person may be someone in your contact list, a colleague sharing the same active directory, or even an external contact from a social networking friend list.
Quick access to Microsoft One Notes. Your app can now access your digital “post-it” and share them with other people in a real-time fashion.
Access to Sharepoint data. Many companies around the world are using Sharepoint as their main content management system. Microsoft Graph API allows developers to access some pieces of data from the SharePoint instance. For example, you have access to the document libraries (sites, subsites, items) and the associated resources URL.
Structure your own data. Microsoft Graph offers you the flexibility to set up your own data format if none of the built-in formats doesn’t match your need. They are called Open extensions or Scheme extensions
Notification pushes. You have a web service that awaits external messages and you want to be contacted as soon as valuable data is available on the spot. The Microsoft Graph APIs offer you the easiest way to do that. You just need to register your web service URL to the Microsoft Graph and when your service needs to be contacted back and what kind of data is it expecting to get. After the subscription is finished, the Microsoft Graph API automatically pushes notifications to your web services with the desired data.
User and group management.

This last feature is the central point of interest because Microsoft Graph APIs are able to talk with the Active directory system either on-premise (using Federated as authentication type )or Azure active directory services (authentication type is Managed in this case). We manage here all permissions and authorizations for each user or group in the system by granting to or revoking from them a specific role.

How to start with Microsoft Graph from scratch

We will create a Microsoft Outlook account, populate it with some data like the user’s profile, add some contacts with their respective data, create events, and add bookmarks on the user’s calendar. Afterward, we will use Microsoft Graph API to extract those data using the Microsoft Graph test tools. We’re showing you how to perform your first step into it. The process is still the same when querying data from the MS cloud.

Create an outook.com account or use an existing one

In this example, we created the account of johndoeu201711 and then we add extra details on the user’s profile. The figure below shows all outlook components.

We also added 02 persons to his contact list. On his calendar, we create a new event. Next, we go to his OneDrive space and create there an excel file named Exel1.xls. We also create a new Outlook task from the Tasks menu.

Configure the account to use Microsoft Graph

We go to the Microsoft Application Registration and get our appID and secret from https://apps.dev.microsoft.com. The platform will show you your secret key, this key is private and you need to note it in a safe place.

Once the secret key is generated, you can finalize the last step as seen in the figure below.

It’s time to test the Microsoft Graph using the Graph Explorer online tools https://developer.microsoft.com/en-us/graph/graph-explorer

At the first login, Microsoft Graph is showing the permissions he needs. If you’re ok, hit the Yes button to go to the next step

The Graph Explorer dashboard:

Query tools:

This option is used to specify the current REST verb.

V1.0 is selected because we want to use the stable revision of the Microsoft Graph API, the other option is “beta”.

The URL bar is the place where you enter the REST resource you want to fetch

Some basic operations:

To get your profile: select GET verb and use the address https://graph.microsoft.com/v1.0/me/

To get all the account message, run the query https://graph.microsoft.com/v1.0/me/messages

In the Response Preview pane, you can see all the messages in JSON format.

To get all our contacts, run the query https://graph.microsoft.com/v1.0/me/people

To list the content of the user’s one drive https://graph.microsoft.com/v1.0/me/drive/root/children

To list the user’s events https://graph.microsoft.com/v1.0/me/events

We can also search a specific file stored in One Drive storage by name:

To search the created excel file named ‘Exel.xls’, run the query https://graph.microsoft.com/v1.0/me/drive/root/search(q=’Exel‘)

The MS Graph API will return all the matching files with metadata like the creation date, the path, the size, the last user modifying the file and the modification date, the file URL, etc.

The graph API example below shows how to use C# to send emails using Microsoft Graph API C# SDK.

public async Task SendEmail()
{
// Arrange.
GraphService graphService = new GraphService();
string subject = "Test email from ASP.NET 4.6 Connect sample";
string bodyContent = "<html><body>The body of the test email.</body></html>";
List<Recipient> recipientList = new List<Recipient>();
recipientList.Add(new Recipient
{
EmailAddress = new EmailAddress
{
Address = userName
}
});
Message message = new Message
{
Body = new ItemBody
{
Content = bodyContent,
ContentType = BodyType.Html,
},
Subject = subject,
ToRecipients = recipientList
};
 
// Act
Task task = graphService.SendEmail(client, message);
 
// Assert
Task.WaitAll(task);
}

The GraphService is the main wrapper to interact with remote services, the method SendEmail will send all the parameters to the service.

Easy access to documentation and support

Microsoft Graph is a well-documented project. As a Microsoft product, you have full support from Microsoft and the official website contains a lot of code snippets for different programming languages. Many enthusiastic developers also contribute to the SDK and many source codes are available on GitHub.

The roadmap

Data location and data variety are now the heart of the digital world. Even the smallest information is so precious and mining them is the gold rush for almost all digital companies. With Microsoft Graph and its API coupled with his favorite programming language, the developer can grab all those data, integrates them into their business rules, or cross join them to extract all valuable pieces of information to deliver profitable tools.

This is exactly the goal of Microsoft Graph. Finally, you should be aware that according to recent statistics, 85% of all fortune 500 companies use Microsoft Graph in their system. This is real proof that Microsoft Graph is a very promising technology for the next years.