DISCLAIMER I am the maintainer of drupal-jsonapi-params (DJAP for short). DJAP stands for “drupal-jsonapi-params” coined by Stuart Clark aka Deciphered, the creator of Druxtjs (Nuxt + Drupal) project. Now, let’s talk about how DJAP can help JavaScript developers working on a decoupled site using Drupal CMS’s JSON-API.
Background
When fetching information from a Drupal backend, we quite often have to use some filters. The documentation page on Drupal.org provides an excellent guide on how to achieve this.
Example A: To get node articles that are promoted or sticky and created by admin,
You would come up with a query parameter as follows:
filter[and-group][group][conjunction]=AND&filter[or-group][group][conjunction]=OR&filter[or-group][group][memberOf]=and-group&filter[uid.name][condition][path]=uid.name&filter[uid.name][condition][value]=admin&filter[uid.name][condition][memberOf]=and-group&filter[sticky][condition][path]=sticky&filter[sticky][condition][value]=1&filter[sticky][condition][memberOf]=or-group&filter[promote][condition][path]=promote&filter[promote][condition][value]=1&filter[promote][condition][memberOf]=or-group
Breaking the above query down for clarity:
// Create proper AND and OR groups.
filter[and-group][group][conjunction]=AND
&filter[or-group][group][conjunction]=OR
&filter[or-group][group][memberOf]=and-group
// Filter by user name 'admin'.
&filter[uid.name][condition][path]=uid.name
&filter[uid.name][condition][value]=admin
&filter[uid.name][condition][memberOf]=andgroup
// Filter for nodes which are marked as sticky
&filter[sticky][condition][path]=sticky
&filter[sticky][condition][value]=1
&filter[sticky][condition][memberOf]=or-group
// Filter for nodes which are marked as promoted.
&filter[promote][condition][path]=promote
&filter[promote][condition][value]=1
&filter[promote][condition][memberOf]=or-group
Assuming we use Axios in our project, a fetch would look something like the below:
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
We can also have granular comments to enhance readability:
As you can see, the library solves code readability issues and vastly improves developer experience.
For more details about available methods, please check the documentation on the Project Page.
Closing Words
Drupal JSON-API Params is an open-source project. Please spread awareness if you like an open-source project by sharing it with others. If you are using the project and would recommend it to others, please consider starring the project on GitHub and on other platforms like Drupal.org.
