Recently at ClearPeople, we have been involved in some R&D activities and customer PoCs (Proof of Concepts) to attempt to take advantage of the Microsoft API Ecosystem. In this article, we want to post some insights about the different options we have found.

After discussing this with a few clients, our intention was to aggregate information from different systems like Yammer, Office 365 groups, SharePoint, etc, in kind of a “Delve home page on steroids” in order to make it more relevant to actual client use cases.

The idea behind Microsoft Graph is very valid and there is no doubt that it will be an incredibly powerful tool as it matures across the multiple endpoints. If you are a “Lord of the Rings” fan, you could say that Microsoft Graph is “One Endpoint to rule them all”. This is the central idea that motivated Microsoft to build and launch Graph, allowing us to get information from across your favourite Microsoft system(s).

But the immediate challenge you bump into is that your path is currently split in two main directions: The current limited Microsoft Graph API or the full API of each specific service. 

Here is the image from Microsoft:

Microsoft graph

Source image:  

Expanding the “Other Office 365 APIs”, we would have something like:

Microsoft graph

What are the differences?

We see two main differences between the Microsoft Graph API, and the specific service API:
  1. An Authorization token issued for a specific service, which is not valid for another service. So, if you negotiate an OAuth Bearer Token for the Outlook service API, it won’t be valid for a OneNote API request. In contrast, when using Microsoft Graph, you have a common Endpoint (in other words, you get the data using the same entry point for multiple requests), so once you are Authorized with a valid Token, you can request information from any endpoint available.
  2. A lot of information is (currently) not available through the MS Graph API (for instance, SharePoint Search). In contrast, the specific application APIs will often be far richer in capability and you will therefor need to call the specific service API in all the cases where you want to get some data that is not available as a MS Graph endpoint. And in real life, this is most of the time.
Microsoft graph

The following image summarises the main operations that – at the point of writing - can be done using MS Graph API:

MS Graph API

There is also a “Beta” API version containing the same endpoints, in addition to other endpoints that are not production-ready yet.

graph MS
Arguably, the most important addition we find in the Beta API version is the SharePoint endpoint. If you want to query SharePoint, you can use this beta endpoint, while keeping in mind that it is currently very limited, and only provides few information about Sites and Lists.

Here are the available SharePoint endpoint query parameters:

SharePoint endpoint query parameters

Limitations of the MS Graph API

As we already pointed out above, many operations are not yet supported in the MS Graph API. In addition, you should be very careful when using the Beta endpoint, as is still quite unstable. 
The most important limitations in our opinion are:
  1. Requests to SharePoint only allow Sites and Lists. Search API is not supported, and even when you get List items, you cannot apply complex queries.
  2. Yammer data is not supported. If you want to get Yammer data, you have to use the Yammer API and deal with the Yammer Login process. Microsoft Graph has a Groups endpoint, but is not returning groups created from Yammer, so the only way of getting Yammer data is from the specific Yammer API.
  3. Information regarding “trending” items is limited as well, and still in Beta. So, if you need more complex queries you need to query directly the Office Graph using Graph Query Language.

Office Graph vs MS Graph

Often people confuse Microsoft Graph API with Office Graph. As explained above, the Microsoft Graph API is a common API to get data from most of the Ecosystem of Microsoft cloud services. Office Graph however is “just” another service within Office 365. So, using MS Graph you can get information collected by Office Graph although you should note that (at the time of writing) not all the information gathered by Office Graph will be available to MS Graph.

An interesting note for those that are not aware is that Yammer is one of the services that provides information to Office Graph and the following provides a bit of historic context to the evolution of Office Graph.

Office Graph

Office Graph is the engine driving the Delve experience. And the Office Graph engine is powered by Machine Learning, constantly learning from information collected about you and your interactions with Office 365.

Office Graph Delve

A great definition of the Office Graph, from this article

Office Graph

What kind of information we can get from Office Graph?

The easiest way to answer this is: “whatever that you can get right now from Delve”. 

The approach to get info from the Office Graph is through the SharePoint Search REST API, adding a specific querystring to indicate we want to get Office Graph information. The syntax is called the Graph Query Language (GQL). Some samples here:

//Objects related to current user (ie – ME)
//Objects related to actor 342
//Objects trending around current user (trending = action type 1020)
/_api/search/query?Querytext=’*’&Properties=’GraphQuery:ACTOR(ME\, action\:1020)’
//Objects related to current user and actor 342
/_api/search/query?Querytext=’*’&Properties=’GraphQuery:AND(ACTOR(ME)\, ACTOR(342))’
//Objects recently viewed by current user and modified by actor 342
/_api/search/query?Querytext=’*’&Properties=’GraphQuery:AND(ACTOR(ME\, action\:1001)\, ACTOR(342\, action\:1003))’
//People for whom the current worker works with
/_api/search/query?Querytext=’*’&Properties=’GraphQuery:ACTOR(ME\, action\:1019)’
//Objects related to actor 342 with ‘Delve’ in the title

The returned data is not very easy to understand, as it depends on what you are requesting. Actions are typed following this table:

Office Graph Actions

Important to note, that the Query Graph is “read-only”, meaning you cannot feed data (i.e add an interaction, promote a document, etc.).

When to use Microsoft Graph or the specific service Endpoint?

Following diagram tries to answer that question:

Microsoft Graph


Author bio

Luis Mañez
Luis Mañez
Atlas Chief Architect & Microsoft MVP
I help find the best technical designs to meet client needs and act as tech lead to build great solutions. I have fun with some R&D tasks, always trying to improve our tools and processes, and I often help the Microsoft community as a blogger and speaker, contributing to open source projects.


comments powered by Disqus

Related Articles

Sign up to our ClearThought newsletter

Get inspired and learn something new by subscribing to our FREE newsletter. It’s full of ClearPeople's thought-leadership whitepapers, blogs, events, and much more. We promise to not use your email for spam.

Closing this message and/or accessing our website tells us you are happy to receive all cookies on the ClearPeople website.
However, if you would like to, you can change your cookies settings at any time.