Tuesday, May 16, 2017

The Office Graph is dead, long live the Microsoft Graph!

Yesterday Microsoft announced two new Insights endpoint (in beta) to the Microsoft Graph in addition to the trending one which was already there. The new endpoints are:
  • Used - returns the most relevant documents that a user viewed or accessed
  • Shared - files shared with or by a specific user
All great news, but at the same time Microsoft announced discontinuation of the Office Graph GQL API’s – effectively killing the last remains of what was formerly known as the Office Graph. This means as of August 31st 2017, calls using GQL on the SharePoint search API will no longer work.

By June 1st you need to add the parameter EnableLegacySPOGraph=true to your GQL calls to extend the life until the final cut off date August 31st.

rip graphReaper and halo’s!
GQL v1 preleased way back in 2014 and the documentation on MSDN was updated as late as of January this year. Instead of getting a GA of v1 or maybe even GQL v2, we are now getting an even blacker box with fewer knobs to turn. So even though this is huge for the Microsoft Graph, which it is, it feels like two steps backward.

I also suspect Delve might use it's own API behind the scenes, hiding all the goodness from non-Microsoft developers. Delve at the beginning used GQL, then moved to custom protocol handlers, and now newer REST services to retrieve data.

And what ever happened to adding custom signals to the Graph?

The updated GQL documentation article goes a long way to describe how you can transition some of the GQL calls over to the Microsoft Graph Insights API, and I recommend you reading them to see how you can transition your GQL applications. But as of today there are gaps which may prevent developers from making the transition – and we just have to trust Microsoft to fix these before August 31st(?).

Personally my use of GQL today resides ON SharePoint pages, meaning the calls are executed in JavaScript on SharePoint pages with SharePoint auth. Calling into the Microsoft Graph today is just a pita from a browser SharePoint context unless you’re working with single page apps. You have to rely on ADAL.js which in itself is a great library, but not suitable for parts implementation today.

Read the article Call the Microsoft Graph API using OAuth from your web part which offers guidance for SharePoint Framework web parts, and you might be discouraged as well.

So how does this effect you?

You have an easy time transitioning if you…

  • …have a provider hosted add-in or single page application using simple GQL calls without and/or or custom weight ranking.
  • …are using ADAL in your existing app, and have are using simple GQL calls.

You have a hard time transitioning if you…

  • …are using GQL as part of SharePoint search web parts or JavaScript on a SharePoint page.
  • …are using and/or to combine signals for several people or signal types in one call.

    Example: give me all documented modified by Bill AND Ted. This will require one call per person in the Microsoft Graph, and you need to get a big enough result set to compare the two and find common documents. Instead of one simple GQL call.
  • …are combining GQL with KQL to limit the results based on terms or properties of the content.

    Example: give me all recent document of type Excel, or give me all trending documents in site A.

My roadmap wish list

Here’s a list of gaps I’d like to see fixed in order of priority:
  1. Allow calls to Microsoft Graph from a SharePoint page context without hassle
  2. Add filter parameters to the Insights API’s to filter on file type and location/path
  3. Allow complex queries with and/or to reduce number of calls and data processing in the application
I do understand the move from Microsoft on moving API’s to the Microsoft Graph and deprecating API’s which have been in preview for almost 3 years – but I still disagree on the direction. Come august 31st and we’ll see what happens, and in the mean time I’ll remove my Collaboration Graph app from the Office store, as it will soon stop working. It’s a single page app, but uses complex GQL statements, so not a good candidate for migration.

I’ll end this with the promo video for the fun “Battle of the Graph” session I participated in at Ignite 2015.