Outlook REST API vs Microsoft Graph

33
votes

I am working on an application that needs to retrieve and edit calendar events from Outlook.com and Office 365. I have seen there are 2 options:

  1. Outlook REST API
  2. Microsoft Graph

They seem to have pretty much the same interface. I saw that Outlook REST API has support for notifications (webhooks), Microsoft graph does not? So, which one to choose? What are the advantages/disadvantages and why are there two API's?

1
outlook-restapimicrosoft-graph-api

1 Answers

40
votes

To retrieve and edit calendar events from Outlook.com, Microsoft Graph API and Outlook REST API endpoints work. If you require Webhooks for an app you are planning to use in production, then you need to use Outlook REST API v2.0 endpoint. We have Webhooks available in preview on Microsoft Graph, and are working to GA them, so you can use them in your production apps in the future. If you don't need Webhooks for your app, then you can use Microsoft Graph v1.0. Both Microsoft Graph and Outlook REST API endpoints are fully supported.

Now on to why there are 2 endpoints. Outlook REST API v1.0 was launched in October 2014, and we offered an improved v2.0 version in November 2015. It has the latest greatest Outlook features exposed through APIs. Microsoft Graph v1.0 is a convenient endpoint, we launched in November 2015, for an app to access information from multiple Microsoft services, for example, Outlook, One Drive, and Azure Active Directory. In fact, when you make a request to Microsoft Graph v1.0 endpoint for any Outlook features, the request gets routed to Outlook REST API v2.0 endpoint under the covers. So the API sets are same by design!

We are working hard to close any gaps between individual service API endpoints (Outlook REST APIs, OneDrive APIs, AAD Graph API etc.) and Microsoft Graph, but there will be a small delta for two reasons.

  1. Individual services may have entities that have the same name but mean something different. For example, both Outlook and OneDrive have "folder" but they mean different things. In this case, we need to rationalize the Microsoft Graph API schema to make it clear to you which entity you are accessing when going through Microsoft Graph API. Folder was available in Outlook API v1.0 endpoint, and we renamed it to MailFolder in Outlook API v2.0 endpoint, and it was exposed as well through Microsoft Graph API v1.0. So, you may always see some features or APIs exposed in an individual service endpoint for some time before the same feature or API is exposed through Microsoft Graph.
  2. Some horizontal capability, for example, Webhooks may be available in Preview or GA earlier in a service endpoint before it is available in Microsoft Graph. This is due to Microsoft Graph API being a newer endpoint compared to the individual service endpoints. Over time, this list of gaps is expected to come down to zero.

Our recommendation is for you to use Microsoft Graph as long as it has the features/APIs you need in production to support your production apps, or at least in Preview to support app development. This makes it easy for you, in the future, to expand your app functionality requiring access to multiple Microsoft services, without changing endpoints. You can use individual service endpoints such as Outlook REST API if you need a feature that is only available in the individual service endpoint, either in production (v2.0) or as preview (beta).