Table of contents

Versioning | Graph API concepts

Bryan Lamos|Last Updated: 8/29/2016
|
2 Contributors

Applies to: Graph API | Azure Active Directory (AD)

This topic summarizes the version differences for Azure Active Directory (AD) Graph API entities and operations. You must specify the version of an operation that you want to use by including the api-version query string parameter in your request. Requests without an api-version parameter will be rejected and return a (400) Bad Request response. If your service calls an older version of an operation, you can choose to continue calling the older version, or modify your code to call a newer version. Any differences in functionality between versions are outlined in the documentation for the entity upon which you are performing the call.

Important

Azure AD Graph API functionality is also available through Microsoft Graph, a unified API that also includes APIs from other Microsoft services like Outlook, OneDrive, OneNote, Planner, and Office Graph, all accessed through a single endpoint with a single access token.

Beginning with Azure AD Graph API version 1.5, the api-version parameter value for General Availability (GA) versions is specified as a numeric value. The following URL shows how to query the top-level resources for tenant domain contoso.com using Graph API version 1.5: https://graph.windows.net/contoso.com?api-version=1.5. For previous versions of Graph API, the api-version parameter value is specified as a date string in the following format: YYYY-MM-DD. The following URL shows how to query the top-level resources of the same tenant using the 2013-11-08 version of the Graph API: https://graph.windows.net/contoso.com?api-version=2013-11-08. For preview features, the api-version parameter value is specified using the string “beta” as follows: https://graph.windows.net/contoso.com?api-version=beta.

API contract, versioning and breaking changes

We will increment the API version number for any breaking changes to the API, in order to protect client applications. We may choose to increment the API version for non-breaking changes too (for example, if we add some significantly large new capabilities).

So, what constitutes a breaking change?

  • Removing or renaming APIs or API parameters
  • Changes in behavior for an existing API
  • Changes in Error Codes & Fault Contracts
  • Anything that would violate the Principle of Least Astonishment

Note:The addition of new JSON fields to responses does not constitute a breaking change. For developers who generate their own client proxies (like WCF clients) our guidance is your client applications should be prepared to receive properties and derived types not previously defined by the Graph API service. Although Graph API is not yet OData V4 compliant at the time of this writing, it still follows the guidance described in the Model Versioning section in the OData V4 spec.

When we increment the major version of the API (for example from 1.5 to 2.0), we are signaling that all support for existing clients using previous 1.x or earlier versions will be deprecated and no longer supported after 12 months. Please see the Microsoft Online Services Support Lifecycle Policy for more details.

Supported versions

The following versions have been released for the Graph API.

Version beta

The Graph API features currently in preview can be found in either the Preview Features section in Graph API concepts, or on the Graph Team Blog. Beta features require the “api-version=beta” query string parameter. When the Graph API team believes that a preview feature is ready for GA, we will add that feature to the latest GA version (or if it constitutes a breaking change this would result in an incremented new version number). We make no guarantees that a preview feature will be promoted to GA.

For the beta version, we will try to avoid any breaking changes as much as possible, but we will not guarantee it. Client applications using the beta version should expect breaking changes from time to time. Please see Supplemental Terms of Use for Microsoft Azure Previews.

Version 1.6

This section lists the changes for Graph API version 1.6.

Graph API version 1.6 introduces the following feature changes:

Entity changes

EntityChange Description
ApplicationAdded the addIns property, which defines custom behavior that a consuming service can use to call an app in specific contexts.

Added the serviceEndpoints navigation property, which contains the collection of service endpoints that are available for discovery.
LicenseDetailNew entity that contains license details for a user.
ServiceEndpointNew entity that contains service discovery information.
ServicePrincipalAdded the addIns property, which defines custom behavior that a consuming service can use to call an app in specific contexts.

Added the serviceEndpoints navigation property, which contains the collection of service endpoints that are available for discovery.
SubscribedSkuAdded the appliesTo property.
TenantDetailAdded the trustedCAsForPasswordlessAuth property, which contains the set of certificate authorities used to validate the trust chain while performing password-less authentication.
TrustedCAsForPasswordlessAuthNew entity that represents a set of certificate authorities to validate the trust chain while performing password-less authentication.
UserAdded the creationType property, which is used to indicate that the user is a local account.

Added the signInNames property, which contains the collection of sign-in names used by a local account user to sign in to an Azure Active Directory B2C tenant. This property is renamed from alternativeSignInNamesInfo in beta.

Added the licenseDetails navigation property.

Complex type changes

TypeChange Description
AddInNew type used to define custom behavior that a consuming service can use to call an app in specific contexts.
CertificateAuthorityInformationNew type that represents a certificate authority used when validating the trust chain while performing password-less authentication.
KeyValueNew type that contains a key-value pair that defines a parameter that a consuming service can use or call on an application specified in an AddIn.
ServicePlanInfoAdded the appliesTo property.

Added the provisioningStatus property.
SignInNameNew type to hold information about a sign-in name that can be used by a local account user to sign in to an Azure Active Directory B2C tenant. This type is renamed from LogonIdentifier in beta.

Action and function changes

FunctionChange Description
changePasswordNew action that that can be called to enable the signed-in user to change their password.

Version 1.5

This section lists the changes for Graph API version 1.5.

Graph API version 1.5 introduces the following feature changes:

  • The schema namespace of Graph API has changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices. This affects all entities and complex types exposed by Graph API.

  • Support for directory schema extensions has been added. This allows you to add properties that are required by your application to directory objects. The following entities support schema extensions: User, Group, TenantDetail, Device, Application, and ServicePrincipal. To support directory schema extensions: the ExtensionProperty entity has been added, the extensionProperties navigation property has been added to the Application entity, and a new function, getAvailableExtensionProperties, has been added to return the registered extension properties of supported directory objects. For more information about extending the directory schema, see Directory schema extensions.

  • The way in which permissions are represented has changed and is more tightly aligned with OAuth 2.0 concepts as well as with the way permissions are represented in other Azure components. The Permission entity has been removed and has been replaced with the OAuth2PermissionGrant entity. This entity represents delegated OAuth 2.0 permissions scopes that arrive in an OAuth 2.0 access token scope claim. Additionally, the new AppRoleAssignment entity represents application roles that can be assigned to users, groups and service principals. Two related complex types have also been added: AppRole and OAuth2Permission. This change has precipitated renaming some properties and adding others in the following entities: Application, Group, ServicePrincipal, and User.

  • The Role entity is renamed to DirectoryRole.

  • The RoleTemplate entity is renamed to DirectoryRoleTemplate.

The following tables list the entities, complex types, and functions that have been added, changed, or removed for this release.

Entity changes

EntityChange Description
ApplicationUpdated the appId property from Edm.Guid to Edm.String.

Added the appRoles property, which contains the collection of application roles that an application may declare. These roles can be assigned to users, groups or service principals.

Added the groupMembershipClaims property, which is a bitmask that configures the "groups" claim issued in a user or OAuth 2.0 access token that your application expects. The bitmask values are: 0: None, 1: Security groups and Azure AD roles, 2: Reserved, and 4: Reserved. Setting the bitmask to 7 will get all of the security groups, distribution groups, and Azure AD roles that the signed-in user is a member of.

Added the knownClientApplications property, which contains a list of client applications that are tied to this resource application. Consent to any of the known client applications will result in implicit consent to the resource application through a combined consent dialog (showing the OAuth permission scopes required by the client and the resource).

Added the oauth2AllowImplicitFlow property, which specifies whether this web application can request OAuth2.0 implicit flow tokens. The default is false.

Added the oauth2AllowUrlPathMatching property, which specifies whether, as part of OAuth 2.0 token requests, Azure AD will allow path matching of the redirect URI against the application's replyUrls. The default is false.

Added the oauth2Permissions property, which contains the collection of OAuth 2.0 permission scopes that the web API (resource) application exposes to client applications. These permission scopes may be granted to client applications during consent.

Added the oauth2RequiredPostResponse property, which specifies whether, as part of OAuth 2.0 token requests, Azure AD will allow POST requests, as opposed to GET requests. Default is false, which specifies that only GET requests will be allowed.

Added the requiredResourceAccess property, which specifies resources that this application requires access to and the set of OAuth permission scopes and application roles that it needs under each of those resources. This pre-configuration of required resource access drives the end-user consent experience.

Added the extensionProperties navigation property, which contains the extension properties associated with the application.
AppRoleAssignmentNew entity that is used to record when a user or group is assigned to an application. In this case it will result in an application tile showing up on the user's app access panel. This entity may also be used to grant another application (modeled as a service principal) access to a resource application in a particular role.
ContactAdded the sipProxyAddress property, which specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the contact.
DirectoryObjectAdded the deletionTimestamp property, which indicates the time at which a directory object was deleted. It only applies to those directory objects which can be restored. Currently this is only supported for Application.
DirectoryRoleRenamed from Role.

Added the roleTemplateId property
DirectoryRoleTemplateRenamed from RoleTemplate.
ExtensionPropertyNew entity that allows an application to define and use a set of additional properties that can be added to directory objects (users, groups, tenant details, devices, applications, and service principals) without the application requiring an external data store.
GroupAdded the onPremisesSecurityIdentifier property, which contains the on-premises security identifier (SID) for the group that was synchronized from on-premises to the cloud.

Added the appRoleAssignments navigation property, which points to the set of applications (service principals) that this group is assigned to.
OAuth2PermissionGrantNew entity that specifies an OAuth2.0 delegated permission scope. The specified OAuth delegated permission scope may be requested by client applications (through the requiredResourceAccess collection) calling this resource application. Replaces the Permission entity which is removed from this version.
PermissionRenamed to OAuth2PermissionGrant.
RoleRenamed to DirectoryRole.
RoleTemplateRenamed to DirectoryRoleTemplate.
ServicePrincipalAdded the appDisplayName property, which specifies the display name exposed by the associated application.

Added the appRoleAssignmentRequired property, which specifies whether an AppRoleAssignment to a user or group is required before Azure AD will issue a user or access token to the application.

Added the appRoles property, which contains the application roles exposed by the associated application. For more information see the appRoles property definition on the Application entity.

Added the oauth2Permissions property, which contains the OAuth 2.0 permissions exposed by the associated application. For more information see the oauth2Permisions property definition on the Application entity.

Added the preferredTokenSigningKeyThumbprint property. Reserved for internal use only. Do not write or otherwise rely on this property. May be removed in future versions.

Added the appRoleAssignedTo navigation property, which points to the set of applications that the service principal is assigned to.

Added the appRoleAssignments navigation property, which points to the set of principals (users, groups, and service principals) that are assigned to this service principal.

Added the oauth2PermissionGrants navigation property, which points to the set of user impersonation grants associated with this service principal.

Removed the permissions navigation property
TenantDetailRemoved the tenantType property.
UserAdded the onPremisesSecurityIdentifier property, which contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud.

Added the sipProxyAddress property, which specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user.

Added the appRoleAssignments navigation property, which points to the set of applications (service principals) that this user is assigned to.

Added the oauth2PermissionGrants navigation property, which points to the set of OAuth 2.0 user impersonation grants associated with this user.

Removed the permissions navigation property.

Complex type changes

TypeChange Description
AppRoleNew type that specifies application roles that may be requested by client applications calling this application, or that may be used to assign the application to users or groups in one of the specified application roles.
OAuth2PermissionNew type that represents an OAuth 2.0 permission scope. The specified OAuth 2.0 permission scope may be requested by client applications (through the requiredResourceAccess collection) calling this resource application.
RequiredResourceAccessNew type that specifies the set of OAuth 2.0 permission scopes and app roles under the specified resource that this application requires access to.
ResourceAccessNew type that represents a permission that this application requires.

Action and function changes

FunctionChange Description
getAvailableExtensionPropertiesNew function that returns the full list of extension properties that have been registered in a directory. Extension properties can be registered for the following entities: User, Group, Device, TenantDetail, Application, and ServicePrincipal.
getMemberObjectsNew function that returns all of the Group and DirectoryRole objects that a user, contact, group, or service principal is transitively a member of.
getObjectsByObjectIdsNew function that returns the directory objects specified in a list of object IDs. You can also specify which resource collections (users, groups, etc.) should be searched by specifying the optional types parameter.
restoreNew service action that allows a deleted application to be restored.

Version 2013-11-08

This section lists the changes for Graph API version 2013-11-08.

The following tables list the entities, complex types, and functions that have been added, changed, or removed for this release.

Entity changes

EntityChange Description
ApplicationAdded the owners navigation property, which points to the set of directory objects that are owners of the application. The owners are a set of non-admin users who are allowed to modify this object. Inherited from DirectoryObject.
DeviceConfigurationNew entity that represents the configuration for a device.
DirectoryObjectAdded the createdOnBehalfOf navigation property, which points to directory object that that this object was created on behalf of.

Added the createdObjects navigation property, which points to the set of directory objects that were created by the current object.

Added the owners navigation property, which points to the set of directory objects that are owners of the current object. The owners are a set of non-admin users who are allowed to modify this object.

Added the ownedObjects navigation property, which points to the set of directory objects that are owned by the current object.

Important: Entities that derive from DirectoryObject inherit its properties and may inherit its navigation properties.
GroupAdded the owners navigation property, which points to the set of directory objects that are owners of the group. The owners are a set of non-admin users who are allowed to modify this object. Inherited from DirectoryObject.
RoleAdded the ownedObjects navigation property, which points to the set of directory objects that are owned by the role. Inherited from DirectoryObject.The Role entity was renamed to DirectoryRole beginning with version 1.5. For information about Role, see DirectoryRole.
ServicePrincipalAdded the appOwnerTenantID property.

Added the autheniticationPolicy property. Reserved for internal use only. Do not use. Removed in version 1.5.

Added the createdObjects navigation property, which points to the set of directory objects that were created by the service principal. Inherited from DirectoryObject.

Added the owners navigation property, which points to the set of directory objects that are owners of the service principal. The owners are a set of non-admin users who are allowed to modify this object. Inherited from DirectoryObject.

Added the ownedObjects navigation property, which points to the set of directory objects that are owned by the service principal. Inherited from DirectoryObject.
UserAdded the immutableId property, which associates an on-premises Active Directory user account to its Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.

Added the userType property, which is a string value that can be used to classify user types in your directory, such as “Member” and “Guest”.

Added the createdObjects navigation property, which points to the set of directory objects that were created by the user. Inherited from DirectoryObject.

Added the ownedObjects navigation property, which points to the set of directory objects that are owned by the user. Inherited from DirectoryObject.

Complex type changes

TypeChange Description
ServicePrincipalAuthenticationPolicyReserved for internal use only. Do not use. Removed in version 1.5.

Action and function changes

FunctionChange Description
assignLicenseNew service action that updates a user with a list of licenses to add and/or remove.

Version 2013-04-05

This is the base version of the Graph API.

Additional resources

© 2017 Microsoft