Howdy folks,

We’ve seen a few posts recently on Stack Overflow from developers asking whether they should be using Microsoft Graph (graph.microsoft.com) vs Azure AD Graph (graph.windows.net).  So we thought we’d provide some guidance, as well as a bit of a roadmap to clarify things, for new and existing developers who require directory-based features. In general, we recommend the use of Microsoft Graph over Azure AD Graph, as Microsoft Graph is where we are investing for Microsoft cloud services.

Roadmap for AAD Graph and Microsoft Graph

First of all, we’ll lay out the roadmap for Microsoft Graph (as it is related to Azure AD Graph functionality).  In each of the sections below we’ll also highlight the opportunities and implications for developers.

Two endpoints, different functionality

Currently (as of 7/8/2016) Microsoft Graph supports most of the directory features that Azure AD Graph supports, but not all.  In some cases, Microsoft Graph supports functionality that is not in Azure AD Graph (such as ability to make $select projection queries).

Even with those gaps, we strongly recommend that developers start using Microsoft Graph over Azure AD Graph, unless those specific gaps prevent you from using Microsoft Graph right now.  For a list of the high level gaps, as of 7/8/2016, please see the end of this blog post for more details.

Microsoft Graph closing the gap with Azure AD Graph

The Microsoft Graph team is working hard to close the gap between Microsoft Graph and Azure AD Graph functionality, making it easier for developers to choose Microsoft Graph.  We will also start to introduce newer directory features on Microsoft Graph (and in some cases only on Microsoft Graph).  You’ll start to see the gap closure and new features over the coming months.  Please monitor both http://dev.office.com/blogs and the Microsoft Graph changelog to see this happen real-time so to speak!

Microsoft Graph supports all functionality exposed by Azure AD Graph

At some point in the near future (we hope within 6 months) Microsoft Graph will support all functionality that Azure AD Graph offers (and more).  At this point developers building new apps (or integrating an existing app with Microsoft cloud services) will be directed to use Microsoft Graph in favor of Azure AD Graph.  For newly registered apps we may prevent the app from calling Azure AD Graph.

NOTE: For existing applications that already use Azure AD Graph , nothing changes and it’s business as usual . The Azure AD Graph GA endpoint will remain fully available for all applications including production applications.  We will continue to closely monitor this API, fix service issues and strive to continue to provide 99.99% service availability.

For developers with existing apps that call Azure AD Graph, we will provide guidance for those who want to switch their apps over to Microsoft Graph (from Azure AD Graph).  Additionally, we’ll do it in such a way that existing users for your applications won’t need to re-consent to your application to access directory data through Microsoft Graph.

Retiring Azure AD Graph

At some point in time, much further out in the future, we will mark the Azure AD Graph as a deprecated API, with clear dates and warnings provided for when this endpoint will no longer service any requests.  This will give developers plenty of time and opportunity to switch over to Microsoft Graph.

We’d like to hear from you

We hope this post clarifies the future of both Microsoft Graph and Azure AD Graph, and how you should think about developing against these APIs.  In general, we recommend the use of Microsoft Graph over Azure AD Graph, as Microsoft Graph is where we are investing for Microsoft cloud services. As always, we’d like to hear what you think of our roadmap plan.

Gaps between Microsoft Graph and Azure AD Graph

At a high level, the following represent the current gaps (as of 7/8/2016) in Microsoft Graph, when compared to Azure AD Graph:

1. Differential query or delta sync for users, groups and organizational contacts
2. Management of applications (on the v1.0 version) including:
   1. Application and service principal entity types
   2. Managing assignment of applications to users and groups
   3. Assigning OAuth permissions to apps
3. Domain entity type
4. Organizational contact entity type
5. Registering directory schema extensions
6. Batching

Partner admin on behalf of capability (for resellers and syndicators)