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?

Quake

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).

Anjelicaanjou

Hi Venkat, thanks for your clarification. Could you also tell me if I need an Office 365 license for an android app that displays some meeting room users' calendar using Outlook REST API v2? Or is it an Outlook account from work enough? I'm quite confused. Thanks! – Dispend

Sorry for the delay in responding. I missed the message notifications. The users of your Android app need to be Office 365 users. To register your app, for your conference room scenario, you need to register your app using an Office 365 tenant. The app would use client credential OAuth flow to access calendars of all conference rooms. So, if you are using Office 365 at work, you can just use your organization's Office 365 account to register your app. Hope this helps ... – Anjelicaanjou

So where do I need to redirect users if they're signing into an Outlook.com account and not an Office365 account? It just takes me to the 365 login page, tries redirecting me to Outlook.com, then takes me back to 365 when I try to do OAuth. – Lindley

@Both graph.microsoft.com and outlook.office.com/api should work for an outlook.com account, once it has been upgraded to Office 365 infrastructure. Can you please send me a private message to my Twitter account "@VRAyyadevara", and I can check?. – Anjelicaanjou

Say I obtained a OAuth access token using Microsoft Graph. Can I use the same to access Outlook REST API endpoints? If not I will have to re-auth all my users in case I hit a limitation with Microsoft Graph and want to move back to Outlook REST API endpoints. – Pyrrho

I have asked it in a separate question here: stackoverflow.com/questions/40763049 – Pyrrho