Migrating from Outlook REST API v1.0 to Microsoft Graph

Version 1.0 of the Outlook REST API was launched in 2015 to provide API access to mail, calendar, contacts, and other data from Exchange Online, with support for Basic Authentication.  Over time, we’ve released major enhancements in Outlook REST API v2.0 and Microsoft Graph, both of which provide richer features, and better performance and reliability than Outlook REST API v1.0. Both Outlook REST API v2.0 and Microsoft Graph use OAuth 2.0 for authentication and authorization, which is a more secure and reliable way than Basic Authentication to access data.

With the planned deprecation of the Outlook REST API v1.0, you can update your app to Microsoft Graph and leverage all the new functionality available there.  This article will give you guidance on the process of upgrading from the Outlook v1.0 REST API to the Microsoft Graph REST API and well as pointing some of the key differences.

Major Differences between Outlook v1.0 and Microsoft Graph:

1. Authorization protocol – Microsoft Graph uses the newer and more secure OAuth 2.0 and OpenID Connect authorization protocols. If you are already using OAuth 2.0 in your app, then you can skip this section. If you are using Basic Authentication to connect to v1.0 of the Outlook REST endpoint, upgrade to use OAuth 2.0 and OpenID Connect by getting access tokens from Azure Active Directory.
2. Supported account types and app types – If you are using Basic Authorization with the Outlook v1.0 REST endpoint, changing to use OAuth 2.0 and OpenID Connect opens up your app to a much larger user base, by allowing you to access users with work or school accounts, as well as users with Microsoft personal accounts. You can also choose to enable user-specific experiences like Single Sign-on (SSO) and support different app types such as Single Page Apps (SPA) and background services like daemon apps. Find out more about the different types of permissions for which you can get access tokens to suit your purpose.
3. API endpoint – The next major difference is that Microsoft Graph endpoint is https://graph.microsoft.com. Change your code to access your REST API calls here. All Outlook v1.0 capabilities are available in Microsoft Graph, and new features are always made available in the Microsoft Graph endpoint. You can quickly try out and compare the APIs on the 2 endpoints: use the Graph Explorer tool for the Microsoft Graph APIs , and the Outlook API Explorer for the Outlook REST API.

Detailed Schematic Differences between Microsoft Graph v1.0 and Outlook v1.0

Casing

Microsoft Graph uses the standard lower camel case as the convention for casing while the Outlook REST API uses PascalCase.

MeetingRequest

Meeting requests messages are returned in the generic Message type in v1 while in Microsoft Graph they are under a separate derived type called “meetingRequest”.

Item

The Item entity in Outlook API has been renamed to outlookItem.

Folder

The Outlook Folder entity in the schema has been renamed to mailFolder in the Microsoft Graph API.

• Renamed Folder as -mailFolder
• Removed the navigation property RootFolder

Attachment

The following date properties have been renamed:

• From DateTimeLastModified to lastModifiedDateTime
• From DateTimeCreated to createdDateTime
• From dateTimeLastModified to lastModifiedDateTime

Message

The following date properties have been renamed:

• From DateTimeReceived to receivedDateTime
• From dateTimeSent to sentDateTime

FileAttachment

• Removed the property IsContactPhoto

Event

The following date properties have been renamed:

• From StartTimeZone to originalStartTimeZone
• From EndTimeZone to originalEndTimeZone
• From Reminder to reminderMinutesBeforeStart
• Changed the type of Start and End from Edm.DateTimeOffset to microsoft.graph.dateTimeTimeZone

RecurrenceRange

• Changed the type of StartDate and EndDate from Edm.DateTimeOffset to microsoft.graph.dateTimeTimeZone

Next Steps

As a starting point, go to the Microsoft Graph documentation where you can find detailed information about the platform. Microsoft Graph also supports a variety of client libraries/SDKs. If you have any questions or concerns as you are working through this migration, please reach out on Stackoverflow; the Microsoft Graph team actively monitors that site.