Problem

If you search for a problem, then you will have it. I joined a project with loads of similar queries splattered across the codebase. 

It was difficult for me to understand the intent of the Developer from the query
~ Developer who takes over the project (or me in the future)

While fixing a bug in such a query, instead of finding the bug, it was easier for me to re-write the whole thing.

It’s a pain to comprehend what is going on in the merge request I’ve to review. All I see is a fetch request and a lot of letters.
~ Developer who reviews the code

Now, we at Factorial go through the Four eyes principle of approving a Merge Request. The Four eyes principle is a requirement that two individuals approve some action before it can be taken. The Four eyes principle is sometimes called the two-man rule or the two-person rule.

However, the changes in query parameters in a merge request are hard to decipher. 

Adding comments to explain what is going on, helps, although I wish I could be more granular.
~ Developer who writes the code

You can add detailed comments for such queries to help your future self or another developer. Please do so.

Solution

Use a library to generate the query. JSON-API is not a Drupal-specific API. There are loads of libraries available to create the filter query. Depending on your taste, you may find the appropriate client implementation over here.

We choose to go with the drupal-jsonapi-params library. 

So our Example A, using “drupal-jsonapi-params” (DJAP for short) would