Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Microsoft Graph Unifies Access to All APIs

Microsoft Graph Unifies Access to All APIs


At the Microsoft Build conference in San Francisco, InfoQ had the opportunity to speak with Gareth Jones, API architect for the Microsoft Graph API which aims at making life easier for developers by providing a unified API endpoint.

With the prevalence of Microsoft products in most businesses around the world, it is interesting to see how Microsoft solves this issue at their scale. Let’s learn what Jones has to say about the Microsoft Graph API.

InfoQ: Hi, Gareth. Can you introduce yourself and your new role at Microsoft?

Gareth Jones: I am an API architect on the Microsoft Graph team. I joined about five months ago after spending a couple of years designing the OneNote API.

One of the last things we did when I was on the OneNote team was to connect OneNote with Microsoft Graph. I thought it was a super-exciting project and that experience made me want to join the team.

InfoQ: What drives your interest in web APIs in general and within Microsoft?

Jones: I first got started with web APIs when I was working on the Visual Studio team. We were building an API to connect to the CodeLens service. That was a new design experience for me. I’d worked on lots of .NET APIs previously and I really enjoyed the process of API design and moving those skills to the Web was a great new challenge. When I got the opportunity to work on the OneNote API, I jumped at it, and through learning to design web APIs I got involved with the broader API community through communities like APICraft and APIStrat.

OneNote was a really interesting API design problem because it has lots of structured data in a hierarchy of pages and sections, but it also has lots of unstructured data in the shape of a very free-form canvas. Fitting those two together into a coherent API was a really interesting space to work in.

InfoQ: Can you tell us more about Microsoft Graph and how it adds value to existing Microsoft web APIs? What are the main use cases it addresses?

Jones: The core value of Microsoft Graph is to unify Microsoft APIs and to have a much simpler developer experience across all of Microsoft’s APIs by bringing them together in a single URI namespace on a single endpoint with a single authentication story; but that alone would be really just a Microsoft API not a Microsoft Graph.

What really makes the Graph is that having all the pieces together allows us to draw intelligent inferences and connections between entities on the API so we can add value and make your application smarter.

For example, our partner Starbucks was able to easily use the People API on the Microsoft Graph to exploit the intelligence of which of your contacts you are most likely to schedule a meeting with for their upcoming Outlook add-in, based on your past communication patterns.

InfoQ: Moving forward, will you keep offering individual APIs in addition to Graph? What is its relationship with OneDrive and its API for example?

Jones: The existing APIs certainly aren't going away but I think you will see new APIs from Microsoft primarily offered on Microsoft Graph because of the extra value it brings.

InfoQ: You just announced a long awaited read/write web API to manipulate Excel spreadsheets stored in the cloud. Can you describe this capability in more detail?

Jones: Excel always had millions of businesses using it on the desktop and now with the Microsoft Graph Excel API it’s much easier to connect that logic directly into your line-of-business application. You can now sync your Excel spreadsheet data with your finance app. With the full richness of chart visualization and data binding to external sources, you can really build exciting solutions.

InfoQ: In term of authentication and authorization, how does Microsoft Graph API solve the complexity of managing security for all those users, applications, and data? This sounds like a daunting task at your scale.

Jones: Well, it's certainly helped by the API community standardizing around OAuth 2.0 so at least the protocol is clear but then historically Microsoft has two different type of authorization systems, one for consumers and one for business.

To simplify that for developers, alongside Microsoft Graph we recently launched the v2.0 of our authentication endpoint which brings together the developer story for application registration and identity management into a single portal and single endpoint for consumer, business and education scenarios in a standard way.

Also, OpenID Connect now is fast becoming an accepted standard for sign-in authentication to complement OAuth's authorization story.

InfoQ: How open and extensible is Microsoft Graph? Can your partners extend this graph with their own data and services like they can extend Visual Studio with visual plugins?

Jones: The plan is definitely for the Microsoft Graph to be fully extensible. Today, some of the APIs on the Graph allow you to decorate entities with your own properties and we are working hard to make that a standard facility across all of the Graph APIs. Eventually our goal is to allow a wider range of customer data to be part of the Graph and take advantage of the smart connections that brings.

InfoQ: Over the past ten years, Microsoft has been developing OData. What is the place of OData today in Microsoft’s API world and its adoption in the broader ecosystem?

Jones: We find OData a really useful tool at Microsoft for modelling and describing our APIs, particularly in terms of the Microsoft Graph which is so focused on the relationship between entities in different APIs and the value in navigating those relationships.

OData has been evolving over the years to something which is now very compatible with modern REST APIs and recently been standardized at the ISO level so we feel very comfortable in it as the basis of a strong interop story.

Of course, we recognize that there is a lot of energy in the community around OAI/Swagger so we want to make sure that we have a great story there as well.

The Microsoft Graph provides all its services via OData v4.0 and you can get live metadata by just asking for the $metadata endpoint. A lot of end-user tools like Excel or Power BI or Salesforce can leverage OData to directly consume Graph data. So that can really enable power users to start getting value from APIs before they need to engage developers.

InfoQ: Recently, Microsoft announced it was joining the Eclipse Foundation to work on cloud IDEs based on the Eclipse Che project. Are there plans yet to support Microsoft web APIs, especially Microsoft Graph, within this new generation of IDE?

Jones: There’s nothing specific we’re doing right now in the Graph area, but it’s certainly something we might look at in future, we already have auth libraries and Graph SDKs across loads of platforms including Java, so it’s a reasonable next step from that.

InfoQ: What engineering problems at Microsoft get in the way of delivering all those web APIs and have your development workflows and tools evolved to solve them?

Jones: The hardest problem in joining together a lot of teams at Microsoft with their own APIs to make a coherent Microsoft Graph is in data modeling for the schema.

Here is an example: we have at least three teams at Microsoft in Outlook, Planner, and WunderList that have a representation of tasks all of which have slightly different use cases but clearly overlap by significant amount in term of the data.

Getting a great model for a consolidated API for tasks is a fun problem. You don't want your tasks to buy cheese at the grocery store showing up by default on your kanban board. There isn't really any great tooling in this space for data-model consolidation so we are inventing some of them as we go along.

The real challenge here is getting injected at the right time into the project lifecycle to ensure that a consolidated model is factored into the design at an early enough stage.

InfoQ: Microsoft has recently joined the Open API Initiative. How much is Microsoft using API definition languages such as Swagger, RAML, and API Blueprint?

Jones: API definition languages are everywhere at Microsoft. You'll noticed Swagger being deeply embedded in many Azure API products and Visual Studio has an API client wizard for Swagger. My previous team, the OneNote team, designed their API in API Blueprint and of course OData CSDL is pretty widely used too.

Like everybody else, we'd like to consolidate a little bit and certainly I think you can expect OAS and OData CSDL to be the primary specifications used by Microsoft moving forward.

InfoQ: What is your view on hypermedia APIs? Isn’t it paradoxical to formally define a hypermedia API?

Jones: I think hypermedia is going to be increasingly prevalent in the next few years but not everyone is ready yet. Building flexible systems that can respond to the dynamic nature of a hypermedia response is a mind shift that takes a while to adjust to.

OData gives us some of the best of both worlds. Typical use of OData today is with the relationships predefined but you can ask for the metadata to be woven into response packets and build a completely dynamic system of top of that instead if you are a hypermedia fan.

If you've seen any of the recent Cortana demos where we offer users proactive suggestions about connecting their business and personal lives, it’s easy to draw an API analogy where static relationships simply won't be adequate. You'll need hypermedia to offer these proactive suggestions through an API.

I think this kind of scenario where hypermedia is used to annotate more traditional APIs for things like machine learning is maybe where we will see the first large practical implementation of hypermedia APIs.

InfoQ: What is coming up next in Microsoft API world?

Jones: There are two main pillars that we are investing in for Microsoft Graph: the first is fairly obvious, adding more API coverage so you can just do more things with Microsoft Graph. I'm looking at products like Microsoft Intune and Skype as examples.

The other pillar is to add richness in the smart-intelligence area. We recently added a scheduling algorithm to the graph to the FindMeetingTimes API and we want to add much more like that. We also want to add deeper graph-query capabilities.

InfoQ: There seems to be a continuous resurgence of RPC on the web, such as gRPC from Google. How do you analyze this phenomenon and is there any similar initiative at Microsoft?

Jones: I think our customers have mostly been fairly happy with our pragmatic approach to REST where we add an action or function in OData where it makes sense rather than being dogmatic about REST principles. So perhaps we haven't felt that pressure. Where we definitely do see the limitations of REST every day is in the area of streaming and real-time data. Increasingly, customers expect almost every system to have real-time coworking.

InfoQ: In your experience, how quickly are API developers transitioning from code-driven to contract-driven API development workflows? Is the API tooling ready for this more industrial phase?

Jones: In my experience working with Microsoft teams, developers are super happy to have more formalism because it takes the guesswork out of interpreting a spec. The challenge is perhaps more in getting business people and architects acclimatized to the tools and working with that degree of precision.

With some of the internal tooling that we have been building, we are really focused on designing the docs and the developer experience upfront and including precise metadata in those documents to drive the development process. This ties the schema design process into the real world scenarios for usage of the API and we feel that's really important.

We sometimes see contract-driven design as starting in the middle. We are trying to push upstream to encode the design in the description of the use cases in the API documentation.

InfoQ: What is your vision of the future of web APIs? What’s the next big thing that needs to happen to accelerate usage of APIs across all sizes of enterprises?

Jones: Well, as already mentioned I think that real-time is going to be huge. REST is great for building transactional systems but for dynamic, interactive apps you really need a real-time channel. It’s going to be interesting to see how the API community focuses on this area. I'm probably biased here, but I think you will start to see a lot more consolidation of siloed APIs along the lines of the Microsoft Graph. There is tremendous value you can deliver when you connect smart machine learning with the relationships between entities and different APIs.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p