Posted 20 March 2017 12:00 AM by Luis Máñez, SharePoint and Cloud Solution Architect @ ClearPeople
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:
Source image: https://dev.office.com/chooseapiendpoint
Expanding the “Other Office 365 APIs”, we would have something like:
What are the differences?
We see two main differences between the Microsoft Graph API, and the specific service API:
- 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.
- 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.
The following image summarises the main operations that – at the point of writing - can be done using 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.
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:
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:
- 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.
- 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.
- 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 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.
A great definition of the Office Graph, from this article
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)
//Objects related to current user and 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
//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:
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: