Microsoft Graph or Azure AD Graph

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 10 May, 2017) 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, open extensions, Office 365 groups and much more).

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 April, 2017, 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 https://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 to access directory data (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.

Client libraries

While we continue to support the Azure AD Graph client library, this is only available for .Net applications and it is maintenance mode.  On the other hand, Microsoft Graph client libraries are available on multiple platforms and languages, that enables you to have more choice in how you can use directory data in apps for your customers.

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

Thanks,

Dan Kershaw on behalf of the Microsoft Graph and Azure AD Graph teams