On-Premises Architectural Requirements for the REST API

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

Comments (14)
  1. Filipp says:

    > 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?

    1. Ivan says:

      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.

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

  2. Geoff Duke says:

    What about Exchange 2016 on-prem only deployments? You seem to be saying that this functionality is only available in hybrid configurations.

  3. Benoit Boudeville says:

    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.

  4. Joshua Wortz says:

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

    1. Joshua,

      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.   

  5. Markus says:

    When will the rest api come for on-premise deployments (no hybrid)?

    1. Markus, we have no plans to enable this feature without hybrid.

      1. Markus says:

        Thanks for the answer, but it’s very sad to hear that MS neglects the needs and expectations of their on-premise customers.

      2. EinmalIM says:

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

        1. Caayn says:

          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 :(

  6. Alexander Zammit says:

    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?

Comments are closed.

Skip to main content