Remove requirement for ConsistencyLevel header from MS Graph API calls

Remove requirement for ConsistencyLevel header from MS Graph API calls



 Jun 16 2021
2 Comments (2 New)

Some of the advanced query parameters in API calls such as $search and $count require setting a ConsistencyLevel request header. This is unintuitive to developers working with MS GRAPH API , arguably it isn't what request headers were designed for.

It's very unusual to enable query options using headers. The problem is amplified by a poor documentation that fails to mention the header in many places.


The header is required to opt in for eventual consistency. This is just one way to achieve that.

Without knowing the nature of your backend architecture, it doesn't seem like a huge challenge to detect advanced query parameters in the URL, without requiring a header.

From a user perspective is feels like an overengineering. As user I want simplicity and clear documentation, which is not the case here and it made me spend a lot of time to figure this out.



Hi Gregory, I'm the PM for the Advanced Query Capabilities for Directory Objects in MSGraph.

You are absolutely right that our documentation is not great, and we are fixing it. We recently added this article: Advanced query capabilities on Azure AD directory objects with a clear description, many examples and detailed property support. We are also working on updating all the other parts of the documentation that will refer to this article, but it will take some time.


Today we are requiring the developer to consciously send the ConsistencyLevel header, because we don't want to hide the fact that some responses are eventually consistent and some other are not, as it will break apps that expect read-after-write consistency.

Due to other internal implementations we are also requiring $count, and that is definitely something we want to drop in the future, but we currently have not planned the work yet.

Iron Contributor

Hi @Licantrop0 , the fact that `count` is also an unintuitive and occasional requirement, but one that's implemented as a uri parameter whereas `consistencylevel` is an http header only underscores @Gregory_Fonkatz 's point.


Are you able to speak to why advanced queries can't be detected by the service in the first place, vs customers needing to use headers? Does it route the queries to a different infrastructure at a network-appliance level?


I'm a fan of Microsoft Graph, keep up the great work!