On-Premises Architectural Requirements for the REST API

Published 09-26-2016 05:00 AM 39.8K Views

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
Not applicable
> Therefore, in order to support a seamless REST API experience,

> all Exchange 2013 servers must be removed from the load balanced array.

My memories might trick me - but didn't you promise us, that we can seamlesly mix E2013 and E2016 Client Access?

Not applicable
You still can mix 2013/2016 servers behind a LB, but depending on feature-set requirements you may be unable to use some until all servers are 2016. You may be able to test with ensuring all /api and /autodiscover traffic only goes to 2016 nodes in a mixed-version setup.
Not applicable
Exchange 2013 wont have support for REST. Therefore, if you want to consume REST, E2013 should be removed in order to avoid situation where REST request could end up on E2013 and fail. Otherwise, if you arent going to use REST, E2013 can stay in same LB rotatiion.
Not applicable
What about Exchange 2016 on-prem only deployments? You seem to be saying that this functionality is only available in hybrid configurations.
Not applicable
That is correct.
Not applicable
Hi Ross,

From a load-balancer perspective, since the recommendation is to do L7 then you can just do it with smart load-balancers able to do pool selection (e.g. F5, ALOHA/HAProxy) :

- create a RestAPI Pool - monitor /api/healthcheck.htm

- use that pool for the /api/* Uri Path (e.g. with F5 this is done by using an iRule, with ALOHA/HAProxy this is done by configuring the back-end appropriately)

That way, anything aiming at https://exchange.contoso.com/api (whatever the namespace you choose) will target Exchange 2016 CAFE only. If the Autodiscover web service is also involved, then leave only Ex2016 servers in the AutoD pool...

Makes sense ?

Now, this is with L7 and advanced LBs. L4 is not recommended so anyone using a "recommended" implementation should be able to continue coexistence flawlessly.

Not applicable
Will REST be parallel in both feature and functionality to EWS?
Not applicable

We are focusing new platform investments on the REST APIs and the apps for Office extensibility model.  Expect new Outlook functionality like finding meeting times and modern granular permissions models via OAuth to be made available in the REST APIs.  We expect to make significantly fewer investments in EWS so that we can focus our resources on investing in a single modern API that will, over time, enable most of the scenarios that our partners currently use EWS.   

Not applicable
When will the rest api come for on-premise deployments (no hybrid)?
Not applicable
Markus, we have no plans to enable this feature without hybrid.
Not applicable
Hi Ross, can you clarify what part of the REST API is considered to not work On-Prem only?

I can GET https://my.onprem.ex2016/api/v2.0/me/messages and get a list of my inbox messages.

Can we as an ISV move from EWS to the /api/ endpoint for On-Prem only and expect api//... to respond like documented?

We have different customers where some use On-Prem only, some Hybrid and some Online only. Would be nice to see those three scenarios inside your "one endpoint to rule them all" strategy ;)

Not applicable
Thanks for the answer, but it's very sad to hear that MS neglects the needs and expectations of their on-premise customers.
Not applicable
That's a good tip EinmalIM.

I'm looking at extending our current application with Exchange support through the Graph API. But the biggest problem right now is the lack of on-premise support. So we'll probably end up with needing to support multiple APIs :(

Not applicable
They key problem with not supporting on-premises is that we end up with different APIs for different Exchange configurations. Do you realize you are shooting yourself in the legs?
Frequent Contributor

Is it possible to use the REST API with the Exchange Server 2019 CU16 too?

Version history
Last update:
‎Jul 01 2019 04:28 PM
Updated by: