Drupal JSON-API Params (DJAP)

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:

Breaking the above query down for clarity:

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.