Enhancing Graph API queries with additional Odata supported queries
I’m excited to share information about additional Odata support and improved paging capability, which will enable more flexible and efficient Graph API queries. We’ve enabled the following in the Graph API:
1. Support for sorting users using $orderby. The default sort order for listing users is by userPrincipalName – we can now also sort by displayName. Here are some examples:
https://graph.windows.net/contoso.com/users?$orderby=displayName?api-version=2013-04-05
https://graph.windows.net/ contoso.com/users?$orderby=displayName&$top=50?api-version=2013-04-05
Note: $orderby can’t be combined with filtering ($filter) today. Our future plans include adding support to sort by other user properties, sorting other object types such as Groups, Contacts, and enabling combinations of Odata queries.
2. Support for $expand, to allow for more efficient queries by returning an object and its linked objects, in one query. For example, if your application needs to get a group and its group membership, without $expand, you would need to make two separate queries: one to get the group object, and a second to get the group’s membership. For example:
These 2 queries can now be efficiently combined into one query by using $expand:
This query will return the list of the group’s member objects and the group object, in one return payload. Note: The current limit of returned objects is 20 – if there were 25 members of a group, only the first 20 members would be
returned. This limit will be reviewed for a future update..
Another example of using $expand, is to get a user and the user’s direct reports – this also previously required two queries, and can now be replaced by one:
This will return a list of user and contact objects that are direct reports to the user, as well as the user object.
This last example shows how we can get a user and the user’s manager with the following query:
https://graph.windows.net/contoso.com/users/adam\@contoso.com?$expand=manager&api-version=2013-04-05
3. Support for paging backwards using a new query parameter “previous-page=true”
Until recently, only paging forward was supported – this can be limiting, especially when you’re designing an application that needs to efficiently go forward and backward between paged results. We now allow you to page backward. Here’s an example:
The following request is for getting the first 5 user objects by specifying the $top=5 option.
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-04-05
The first 5 user objects are returned (default sort order for users is by user principal name), plus a skip token value (odata.nextLink) – the skip token contains the value that marks starting point of getting the
next page of results.
"odata.nextLink":
"directoryObjects/$/Microsoft.WindowsAzure.ActiveDirectory.User?$skiptoken=X'44537074020001000000213A41646D696E34404772617068446972312E6F6E6D6963726F736F66742E636F6D29557365725F31353365353064662D653930382D343836652D383133622D306335646566313666323334B900000000000000000000'"
To get the next page of 5 users, we include this skip token value in the next query:
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-04-05 &$skiptoken=X'4453707402.....0000'
The result of this query will return the next 5 user objects, plus another skip token shown below. Note: when no more skip tokens are returned, this indicates there are no more objects to be returned from the query.
[1] "odata.nextLink": "directoryObjects/$/Microsoft.WindowsAzure.ActiveDirectory.User?$skiptoken=X'4453707…..00000'"
But, now instead of accessing the next 5 users, the application needs to retrieve the previous page of results – the application would execute a new query with the skip token from [1] and include the previous-page=true
query argument, as follows:
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-04-05&$skiptoken=X'4453707.....00000' &previous-page=true
Now the returned result will be the previous paged result of 5 user objects, plus another skiptoken.
Therefore, after each query, the application now has two options: 1. Page forward using the skiptoken value, or 2. page backward by using the skiptoken value and the previous-page=true query argument – this now gives the application a flexible way to process and navigate through large datasets.
Please try it out for yourself.
A simple way to try out and play with these new capabilities, is by using the GraphExplorer at https://GraphExplorer.cloudapp.net, using either your own Azure AD/Office 365 tenant (click on SignIn), or by using the Demo company (click on “Use Demo Company”).
These updates are available immediately for the Graph API. We will continue to introduce new capabilities to enable applications to offer additional features, and we’ll be posting updates here shortly. Please send to us any questions, comments or other feature requests.
Thank you, Ed