Supporting query parameters without $ prefixes in Microsoft Graph

One of the top feature requests we have heard from developers using Microsoft APIs is their preference to not use the ‘$’ prefix in query parameters. We listened and today we are announcing that starting with the /beta endpoint and soon moving into /v1.0 for Microsoft Graph, the ‘$’ prefix in the following query parameters is now optional:

  • select
  • expand (including nested expressions)
  • orderby
  • filter
  • top
  • skip
  • skiptoken
  • count
  • search
  • format

Here is an example of a simple query with Microsoft Graph using query parameters without ‘$’ prefixes:

GET https://graph.microsoft.com/beta/me/messages?select=sender,subject&expand=attachments&orderby=receivedDateTime%20desc&filter=isRead%20eq%20false&top=100&skip=0&count=true

With this new support, the query above yields the same result as this one using the ‘$’ prefixes:

GET https://graph.microsoft.com/beta/me/messages?$select=sender,subject&$expand=attachments&$orderby=receivedDateTime%20desc&$filter=isRead%20eq%20false&$top=100&$skip=0&$count=true

Here is another example of a complex query using query parameters without ‘$’ prefixes in nested form:

GET https://graph.microsoft.com/beta/me/messages?expand=attachments(select=name,size)

Which yields the same result as:

GET https://graph.microsoft.com/beta/me/messages?$expand=attachments($select=name,size)

One thing to note is that the same query parameter with and without ‘$’ prefix cannot be presented together at the top level in a query because they are now equivalent query parameters. The following is an example of a bad query:

GET https://graph.microsoft.com/beta/me/messages?$select=sender&select=subject

This query results in a 400 bad request.

You should continue to use the ‘$’ prefix when the query parameter is in a path segment. For example, here is a request that uses count to get the number of messages:

GET https://graph.microsoft.com/beta/me/messages/$count returns 200

That request succeeds but the following request which excludes the ‘$’ prefix fails because count is considered a path segment rather that a query parameter:

GET https://graph.microsoft.com/beta/me/messages/count returns 400 

We hope you enjoy the option to use query parameters without ‘$’ prefixes in your future queries on Microsoft Graph.

Charlie and the team.

Comments powered by Disqus