En l’anterior article sobre JSON:API ja vam veure els fonaments i els seus avantatges. En aquest article ens centrarem en una cosa molt concreta: com utilitzar filtres amb JSON:API.
És molt habitual tenir un llistat d’elements proporcionats a través d’un endpoint, i que la nostra aplicació (sigui web o mòbil) necessiti només un subconjunt d’aquests elements. Tal com vaig mencionar a l’article anterior, amb JSON:API podem filtrar els resultats sense necessitat de demanar res a ningú, simplement afegint paràmetres a la URL de l’endpoint.
El millor és veure-ho amb un exemple: un llistat de receptes:
https://drupaldemo.omitsis.com/es/jsonapi/node/recipe
Un petit apunt: per veure bé un JSON, pots fer-ho des de Firefox (que ja ho fa de sèrie) o bé instal·lar una extensió a Chrome. N’hi ha unes quantes, jo faig servir JSONView. Per a altres navegadors, no sé com està el tema.
En les receptes veiem que hi ha un camp que representa la dificultat (field_difficulty) i volem filtrar per aquest camp. Amb JSON:API és tan fàcil com afegir aquest paràmetre a la URL:
1filter[field_difficulty]=value
En el nostre cas, per obtenir només les receptes amb dificultat “easy”, seria així:
https://drupaldemo.omitsis.com/es/jsonapi/node/recipe?filter[field_difficulty]=easy
Ara posem-ho una mica més complex: receptes amb dificultat “easy” i amb un ingredient que contingui la paraula «cebollas»:
Grups i condicions
Quan posem un filtre darrere d’un altre, per defecte es comporta com un AND, però podem definir condicions i grups. Aquestes condicions i grups poden estar niats, així que permeten qualsevol tipus de combinació lògica.
Per crear un filtre, la forma bàsica és la següent:
1&filter[nom-filtre][condition][path]=field_nom_camp2&filter[nom-filtre][condition][operator]=%3D (<- símbol '=', treu el que hi ha entre parèntesis)3&filter[nom-filtre][condition][value]=valor_a_filtrar
Si volem crear grups, primer especifiquem el grup i després l’assignem a la condició:
1?filter[nom-grup][group][conjunction]=OR23&filter[nom-filtre][condition][path]=field_nom_camp4&filter[nom-filtre][condition][operator]=%3D5&filter[nom-filtre][condition][value]=valor_a_filtrar6&filter[nom-filtre][condition][memberOf]=nom-grup
Els grups també poden tenir la propietat memberOf, de manera que pots crear grups dins d’altres grups.
Operadors disponibles als filtres de JSON:API
Els operadors que podem utilitzar en les condicions són els següents:
‘=’, ‘<>’, ‘>’, ‘>=’, ‘<‘, ‘<=’,
‘STARTS_WITH’, ‘CONTAINS’, ‘ENDS_WITH’,
‘IN’, ‘NOT IN’,
‘BETWEEN’, ‘NOT BETWEEN’,
‘IS NULL’, ‘IS NOT NULL’.
Abreviatures
Quan l’operador que volem utilitzar és el signe igual, el podem ometre i no posar-lo, de manera que quedaria així:
1&filter[nom-filtre][condition][path]=field_nom_camp2&filter[nom-filtre][condition][value]=valor_a_filtrar
A més, si no volem utilitzar aquest filtre com a grup, el podem escurçar encara més fins a la següent forma, que si recordes, és la primera que vam fer servir:
1&filter[field_nom_camp]=valor_a_filtrar
Filtres i control d’accés
És important recordar que els filtres no impediran que un usuari accedeixi a contingut restringit, ja que estem filtrant des del frontend. El backend és qui ha d’aplicar el control d’accés sobre el contingut i els camps segons els permisos dels usuaris.
Tot i això, per millorar el rendiment (i pel que sembla és una millora molt demanada), és recomanable filtrar tot allò que sabem que l’usuari no hauria de veure. Un exemple típic és filtrar només els nodes publicats:
1Versió curta2filter[status][value]=134Normal5filter[status-filter][condition][path]=status6filter[status-filter][condition][value]=1
I amb això tenim un bon resum dels filtres de JSON:API. En el següent article veurem com incloure referències (taxonomies, usuaris, altres nodes, etc.) i després ja passarem a veure els primers passos de Drupal amb REACT utilitzant JSON:API.