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 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 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.
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
|AAD Graph Capability||Status in Microsoft Graph (March 23, 2018)|
|1. Differential query (aka delta sync) for users, groups and organizational contacts||GA availability with Delta Query.
Delta query on organizational contacts is not available but is planned (see below).
Additionally, certain optimization headers, sync from now and some other parameters are not yet supported in Delta Query, but will be available soon.
|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.
Extensive breaking changes are planned over the coming few months for application APIs, in preview, before this rolls out to Microsoft Graph v1.0.
|4. Partner admin on behalf of capability (for resellers and syndicators who are part of the Cloud Solution Provider program)||GA availability. See CSP support in Microsoft Graph.|
|5. Domain resource type (mainly relevant for Cloud Solution Providers)||GA availability. See Domain.|
|6. Contracts resource type (only relevant for Cloud Solution Providers)||GA availability. See Contract.|
|7. Registering directory schema extension definitions||GA availability. Extending resources with application data is available with Extensions and schema extensions.
NOTE: Not available for extending application or service principal resource types.
|8. Batching||GA availability: See JSON batching|
|9. Missing properties on the User resources (sipProxyAddress, otherMails, licenseDetails)||GA availability: See User for imAddresses and licenseDetails.
otherMails is still not available, but coming soon.
|10. GetObjectsByObjectIds method||GA availability. See getByIds method.|
|11. IsMemberOf method||Not planned. Use checkMemberGroups method instead.|
|12. Manage users in a B2C tenant (set local accounts, sign in names)||Coming soon (preview)|
Dan Kershaw on behalf of the Microsoft Graph and Azure AD Graph teams