On-Premises Architectural Requirements for the REST API
Published Sep 26 2016 05:00 AM 58.8K Views

Update 3/4/2022: The REST API for on-premises mailboxes preview is ending. Please see this blog post for more information.

Hybrid customers are able to take advantage of the REST APIs for both Office 365 and on-premises mailboxes. The REST APIs (Mail, Calendar, and Contact APIs) simplify programming against Exchange by providing a familiar syntax that is designed with openness (e.g., open standards support JSON, OAUTH, ODATA) and flexibility (e.g., granular, tightly scoped permission to access user data). These APIs allow developers to connect from any platform, whether it be web, PC, or mobile. SDKs exist for.NET, iOS, Android, NodeJS, Ruby, Python, Cordova, and CORS for use in single page JavaScript web apps. As announced at Microsoft Ignite, Exchange 2016 Cumulative Update 3 (CU3) includes support for the REST API integration with Office 365. This integration enables customers that are in a hybrid deployment with Office 365 to have a seamless authentication and application experience regardless of mailbox location. In order to take advantage of the REST APIs in your hybrid deployment, you must implement these prerequisites.

Mailbox Requirements

All on-premises mailboxes that will utilize the REST APIs must be located on databases residing on Exchange 2016 servers.

Infrastructure Requirements

All Exchange 2016 servers must be upgraded to CU3 or later. In addition, when upgrading an existing Exchange 2016 server to CU3, /PrepareAD must be executed in the on-premises environment to enable support for the REST specific cmdlets and parameters. While Exchange 2016 and Exchange 2013 servers can coexist in the same load balanced array, Exchange 2013 does not provide REST API integration. Therefore, in order to support a seamless REST API experience, all Exchange 2013 servers must be removed from the load balanced array.

Networking Requirements

From a DNS perspective, the Autodiscover namespace and on-premises client namespace must have Internet DNS records. CU3 introduces a new virtual directory to support the REST API, the /api virtual directory. If you have deployed a firewall or application gateway that inspects and restricts access based on the virtual directory being accessed, you will need to update the appropriate settings to allow access to the REST API virtual directory. The REST API takes advantage of a new Autodiscover method for determining authentication and mailbox location. In order to ensure REST API applications can access the on-premises infrastructure correctly, you will need to update the appropriate firewall or application gateway settings to allow access to the /autodiscover/autodiscover.json virtual directory file.

Hybrid Requirements

The Hybrid Configuration Wizard (HCW), performs the necessary configuration steps to support REST API integration with on-premises environments. Specifically, the HCW adds a new authentication provider and registers a hostname with the Azure security token service. You must also ensure that your on-premises Active Directory is fully synchronized with Azure Active Directory.


We hope you will take advantage of the new functionality and capabilities offered by the REST API in your hybrid deployments. For more information and code examples on the REST API, please see https://dev.outlook.com/.

Ross Smith IV, Principal Program Manager Office 365 Customer Experience

Version history
Last update:
‎Mar 04 2022 08:11 AM
Updated by: