When should I use Outlook REST API vs Microsoft Graph API?

Question

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 API

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?

Answer 1

_{Disclaimer: I'm a Microsoft employee.}

To retrieve and edit calendar events from Outlook.com, both 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. Microsoft has Webhooks available in Preview on Microsoft Graph, and are working to bring them to General Availability (GA), 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.

In other words, 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 Microsoft 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 that we launched in November 2015 for an app to access information from multiple Microsoft services, for example, Outlook, OneDrive, 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 the Outlook REST API v2.0 endpoint under the covers. So the API sets are same by design!

Microsoft is 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 a "folder" entity, but they mean different things. In this case, Microsoft still needs 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 as an Outlook API v1.0 endpoint, and it was renamed to MailFolder in the 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 reduce down to zero.

Microsoft's 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).