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 3/17/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).
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 3/17/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 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.
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
|Capability||Status in Microsoft Graph (March 17, 2017)|
|1. Differential query or delta sync for users, groups and organizational contacts||Available in preview with Delta Query.
Delta query on organizational contacts is not available but is planned (see below).
|2. Organizational contact resource type||In preview. Move to GA is planned.|
|3. Management of applications including:
a. Application and service principal entity types
b. Managing assignment of applications to users and groups
c. Assigning OAuth permissions to apps
|This capability is available in preview only.
Extensive breaking changes are planned over the coming few months for application APIs, in preview, before this rolls out to v1.0.
|4. Partner admin on behalf of capability (for resellers and syndicators who are part of the Cloud Solution Provider program)||Coming soon (preview)|
|5. Domain resource type (mainly relevant for Cloud Solution Providers)||Coming soon (preview)|
|6. Contracts resource type (only relevant for Cloud Solution Providers)||Coming soon (preview)|
|7. Registering directory schema extension definitions||Extending resources with application data is available in preview with Schema Extensions. NOTE: Not available for extending application or service principal resource types.|
|8. Batching||Not available. Planned.|
|9. Missing properties on the User resources (sipProxyAddress, otherMails, licenseDetails)||Coming soon (preview)|
|10. GetObjectsByObjectIds method||Coming soon (preview)|
|11. IsMemberOf method||Not planned. Use checkMemberGroups method instead.|
Dan Kershaw on behalf of the Microsoft Graph and Azure AD Graph teams