Ja hem vist els fonaments de JSON:API i com filtrar, però encara ens falta una funcionalitat molt important: com obtenir els valors dels camps referenciats dins la mateixa consulta.
Amb una REST API tradicional, si tenim un endpoint que ens retorna un llistat de receptes i aquestes tenen categories, el més habitual és que en l’endpoint de receptes només aparegui l’identificador de la categoria. El mateix passaria amb l’usuari: només tindríem l’ID i no els camps que realment ens interessen (nom, cognoms, etc.). Després, amb aquest ID, hauríem de fer una nova petició a l’endpoint corresponent per obtenir la informació necessària.
Això implica una petició general per a les receptes, després n per als usuaris i m per a les categories, on n és el nombre d’usuaris a consultar i m el nombre de categories (a no ser que l’endpoint permeti consultar diversos ítems alhora). Al final, acaben sent moltes consultes, i la solució sol ser crear un endpoint a mida que retorni tota la informació de cop.
Amb JSON:API això no és necessari, ja que podem incloure les referències a la mateixa consulta simplement afegint paràmetres a la URL. El paràmetre que hem d’utilitzar és:
1include=camp_a_incloure
Per exemple, en el nostre JSON de receptes, veiem que hi ha diversos camps referenciats: field_recipe_category, field_image… i, com pots veure en el JSON, hi ha un camp “relationships” dins de cada ítem que només conté dins de data el tipus (type) i l’identificador (id). Aquesta informació per si sola no ens serveix de gaire.
Amb el codi que hem vist abans, en el nostre cas hauríem d’escriure:
1include=field_recipe_category,field_image
Per tant, la URL quedaria així:
https://drupaldemo.omitsis.com/es/jsonapi/node/recipe?include=field_recipe_category,field_image
Si hi fas clic, veuràs que al final del document JSON hi ha un nou element anomenat included, on es mostren totes les entitats relacionades, amb tots els seus camps.
També podríem obtenir la referència d’una altra referència. Per exemple, si tinguéssim un camp de comentaris i volguéssim obtenir també la informació dels usuaris d’aquests comentaris, només caldria afegir això:
1include=field_comments.uid
Com pots veure, és una funcionalitat molt potent, però cal anar amb compte: si inclous massa relacions, les consultes poden arribar a ser molt pesades i trigar massa. Sempre experimenta i troba un equilibri entre potència i rendiment.