In the previous article about JSON:API, we already reviewed the basics and its advantages. In this post, we’ll focus on something very specific: how to use filters with JSON:API.
It’s quite common to have a list of elements provided through an endpoint, and our application (whether web or mobile) only needs a subset of them. As mentioned in the previous post, with JSON:API we can filter results ourselves — simply by adding parameters to the endpoint URL.
Let’s see this with an example — a list of recipes:
https://drupaldemo.omitsis.com/es/jsonapi/node/recipe
A quick note: To view JSON properly, you can either use Firefox (which supports it by default) or install a Chrome extension. There are several available; I personally use JSONView. For other browsers, I’m not sure how it’s handled.
In the recipes, we see a field representing the difficulty (field_difficulty), and we want to filter by that field. With JSON:API, it’s as easy as adding this parameter to the URL:
1filter[field_difficulty]=value
In our case, to get only the recipes with difficulty “easy,” we’d use:
https://drupaldemo.omitsis.com/es/jsonapi/node/recipe?filter[field_difficulty]=easy
Now, let’s make it a bit more complex — recipes with difficulty “easy” that also contain the ingredient “onions”:
Groups and Conditions
When we apply multiple filters, they behave as AND conditions by default, but we can also define conditions and groups. These groups can be nested, allowing for any logical combination of conditions.
The basic structure for creating a filter is as follows:
1&filter[filter-name][condition][path]=field_name2&filter[filter-name][condition][operator]=%3D (<- this means '=', remove what’s in parentheses)3&filter[filter-name][condition][value]=value_to_filter
If we want to create groups, we first define the group and then assign it to a condition:
1?filter[group-name][group][conjunction]=OR23&filter[filter-name][condition][path]=field_name4&filter[filter-name][condition][operator]=%3D5&filter[filter-name][condition][value]=value_to_filter6&filter[filter-name][condition][memberOf]=group-name
Groups can also have the property memberOf, which means you can create groups within groups.
Available Operators in JSON:API Filters
The operators available for use in conditions are as follows:
‘=’, ‘<>’, ‘>’, ‘>=’, ‘<‘, ‘<=’,
‘STARTS_WITH’, ‘CONTAINS’, ‘ENDS_WITH’,
‘IN’, ‘NOT IN’,
‘BETWEEN’, ‘NOT BETWEEN’,
‘IS NULL’, ‘IS NOT NULL’.
Shortcuts
When the operator you need is “equals,” you can omit it, resulting in a shorter version like this:
1&filter[filter-name][condition][path]=field_name2&filter[filter-name][condition][value]=value_to_filter
And if you don’t need to use the filter as a group, you can shorten it even more — like in our first example:
1&filter[field_name]=value_to_filter
Filters and Access Control
It’s important to remember that filters won’t prevent users from accessing restricted content, since we’re filtering on the frontend. It’s up to the backend to enforce access control based on the user’s permissions and what content or fields they’re allowed to view.
However, to improve performance — and this is a highly requested feature — it’s good practice to filter out content the user shouldn’t see. A typical example would be to filter only published nodes:
1Short version2filter[status][value]=134Normal5filter[status-filter][condition][path]=status6filter[status-filter][condition][value]=1
And with that, we have a solid overview of JSON:API filters. In the next post, we’ll look at how to include relationships (taxonomies, users, other nodes, etc.), and then move on to exploring Drupal’s first steps with REACT using JSON:API.