Insights into the Microsoft API Ecosystem

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:

Microsoft graph

Source image: https://dev.office.com/chooseapiendpoint  

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)
/_api/search/query?Querytext=’*’&Properties=’GraphQuery:ACTOR(ME)’
//Objects related to actor 342
/_api/search/query?Querytext=’*’&Properties=’GraphQuery: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
/_api/search/query?Querytext=’Title:Delve’&Properties=’GraphQuery:ACTOR(342)’

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

References

Share:

Add your comment

 
 

 

Archive

Tagcloud

Digital Transformation employee engagement staff satisfaction productivity Microsoft Teams Office 365 Yammer cms content management system agile GDPR Microsoft Graph collaboration Microsoft sharepoint 2016 upgrade migration SharePoint Online 2016 Tech Trends Digital Disruption Context marketing marketing SharePoint 2010 SharePoint 2013 TFS Git security kentico Analytics intranet jquery QA Quality Assurance testing digital workspace content management websites Sitecore sitecore marketplace sitecore module cloud Microsoft Cloud Storage digital strategy technical consulting sitecore modules Experience database Sitecore 7 Sitecore 8 support account management customer experience Data Storage windows azure cms integration front end front end development prototype Cloud Storage StorSimple Front-end Development Layout SharePoint 2013 colour palette UI design website design log viewer sitecore cms website Azure big data business-critical sharepoint accessibility android apple chrome clear people clearpeople debug emulator ios mobile testing opera resize adobe desktop flash ie10 internet explorer 10 metro windows 8 bcsp SharePoint Advanced System Reporter reporting framework ControlMode form control master page placeholder publishing console SharePoint 2007 SharePoint error search search results search values software testing testing scenario audit content information architecture retention schedules PowerShell QuickLaunch scripts SharePoint server 2010 business solutions metalogix replication replicator storagepoint stena technet UK Technet picture library slideshow web part RTM released to manufacturing caml caml query MOSS 2007 query infopath