Quali sono gli strumenti e i pattern che Drupal mette a disposizione per sviluppare un CMS headless?
Prima un ripassino: Drupal e un software free e open-source scritto in PHP, nato agli inizi degli anni 2000 come progetto universitario dello studente belga Dries Buytaert. Nel corso del tempo si e evoluto da CMS fino a diventare un vero e proprio framework; infatti, oggi si parla frequentemente di Drupal come CMF - Content Management Framework - piu che come CMS.
POTREBBE INTERESSARTI ANCHE: Perche scegliere Drupal per siti aziendali complessi
Il grosso salto in questo senso si e avuto durante il passaggio dalla versione 7, che presentava ancora un’architettura basata su codice proprio, alla versione 8, rilasciata nel novembre 2015, in cui sono stati integrati molti componenti Symfony direttamente all’interno del core di Drupal e il template engine di default per il frontend e diventato Twig. Le versioni 8 e 9, quelle ad oggi supportate, utilizzano Symfony 4, mentre per la 10, attualmente in sviluppo, e previsto l’utilizzo di Symfony 5 o, se compatibile con i relativi release schedule, direttamente Symfony 6. Tra i componenti utilizzati, abbiamo DependencyInjection, EventDispatcher, HttpFoundation, Routing, Serializer, Yaml. Queste sono le fondamenta sopra le quali Drupal costruisce a sua volta con i propri mattoni.
Fra le altre cose, dalla 8 Drupal ha anche iniziato a versionare il proprio codice seguendo il Semantic Versioning, tanto che la 9, l’attuale, e sostanzialmente l’ultima versione del branch 8 ripulita dal codice deprecato. Il passaggio per molti siti dalla 7 alla 8 e stato un vero e proprio cambio di paradigma; il passaggio dalla 8 alla 9 e invece molto piu lineare, e lo sara anche quello dalla 9 alla 10.
L’ecosistema JSON:API
Drupal mette a disposizione diverse possibilita. Qui ne vedremo una in particolare, piu completa e supportata rispetto alle altre, e che soprattutto permette di raggiungere il nostro scopo senza aggiungere codice custom, ma solo tramite l’utilizzo di moduli core o contrib appositamente configurati. Questo approccio ruota intorno al modulo core JSON:API.
JSON:API e una specifica che definisce uno standard per l’esposizione e la gestione di dati in formato JSON tramite HTTP. La sua prima stesura risale al maggio 2013, e oggi e alla versione 1.0. Ha un proprio MIME media type registrato, ed e progettato per minimizzare le richieste fra client e server. La specifica e stata definita indipendentemente da Drupal che, in questo senso, si limita a implementarla nel proprio modulo core. Va comunque sottolineato che uno dei responsabili della API-first initiative per Drupal, Gabe Sullice, e anche diventato manutentore della specifica stessa.
Il modulo Drupal JSON:API si trova nel core (anche se non e attivo di default), e permette di esporre i nostri dati in formato JSON:API su endpoint appositi. Gli altri moduli dell’ecosistema che andremo a vedere sono invece moduli contrib, ed estendono le funzionalita del modulo core in modo da rispondere a specifiche necessita di sviluppo. Tutti questi moduli sono supportati da Acquia, l’organizzazione dietro a Drupal, o da altre aziende importanti e attive nel settore, come ad esempio Lullabot o Centarro.
Il primo modulo contrib della lista e JSON:API Extras, che permette di estendere e sovrascrivere il comportamento di default del modulo JSON:API. Ci sono poi Decoupled Router e Subrequests, che possono essere utilizzati, in combo, per risolvere le risorse tramite path alias e ridurre il numero di richieste HTTP necessarie. E poi Consumer Image Styles, utile per gestire le immagini responsive. Vediamo nel dettaglio le funzionalita offerte dal modulo JSON:API Extras:
- cambiare il prefisso dell’endpoint, ad esempio da /jsonapi ad /api;
- decidere di mostrare i contatori nelle collection delle entita; e soprattutto
- fare l’override del comportamento di ogni risorsa esposta.
In particolare, su quest’ultimo punto: per ogni risorsa e possibile cambiare il nome esposto, il path, definire i campi disponibili, oppure disabilitarla del tutto. Ad esempio, se non abbiamo interesse ad esporre gli utenti presenti sul sito, possiamo decidere di rimuoverli da JSON:API appunto tramite Extras. Tutto questo e gestibile direttamente da pannello di amministrazione, senza necessita di scrivere codice apposito.
Abbiamo visto che Drupal espone le risorse quando viene specificato sui loro endpoint l’id univoco della risorsa. Cosa accade pero se il nostro front end non conosce l’id dell’entita che deve richiamare, ma solamente il path alias?
Decoupled router
Decoupled Router ci consente di risolvere proprio questa casistica. Decoupled Router e un altro modulo contrib che fa parte dell’ecosistema di JSON:API e permette di richiamare le risorse tramite appunto path alias, anziche tramite uuid.
In pratica, funziona cosi: una volta attivato il modulo, e possibile inviare le richieste per le risorse a un path specifico, /router/translate-path?path=, concatenando il path alias della risorsa desiderata. Il modulo si occupa quindi di cercare la risorsa nei contenuti del sito, seguendo anche eventuali redirect, fino a recuperare l’identificativo della risorsa. A questo punto, restituisce una pagina che contiene non la risorsa direttamente, ma l’URL di JSON:API della risorsa.
Quindi, ad esempio, facendo una richiesta in GET a /router/translate-path?path=/books/flowers-algernon nel nostro progetto, ci viene restituita una pagina contenente l’URL con lo uuid della nostra risorsa, da poter usare per recuperare i dati che ci servono.
Ovviamente qui rimane un problema, ossia quello della doppia richiesta: una prima per recuperare l’URL, e una seconda per recuperare l’entita. E a questo punto che ci viene in aiuto il modulo Subrequests. Con questo, abbiamo completato il quadro dell’ecosistema JSON:API e possiamo combinare i moduli per ottenere il risultato desiderato con una sola richiesta HTTP. Subrequests permette di inviare piu richieste in un’unica chiamata, e di concatenarle fra loro in modo che una richiesta possa usare i dati restituiti da un’altra.
- Il requestId e l’identificativo con cui etichettiamo ogni nostra richiesta.
- L’uri e il path a cui facciamo la richiesta. RequestId e uri sono obbligatori.
- La action e il tipo di richiesta.
Nella richiesta 2 e inoltre presente la proprieta waitFor: questa viene usata per indicare che questa sottorichiesta dipende dalla risposta di una richiesta precedente. Possiamo infatti vedere che abbiamo costruito l’uri della 2 con i valori ottenuti dalla risposta alla richiesta 1, nello specifico con lo uuid del libro. In definitiva, la richiesta 1 e al path di Decoupled Router che ci restituisce l’id del libro che ci interessa, e la richiesta 2 e al path che ci riporta i dati del libro.
Altre parti dell’ecosistema
Riassumendo, quindi, abbiamo visto come nella nostra architettura ciascuno dei moduli dell’ecosistema prenda le mosse dal precedente e permetta di definirne e specializzarne sempre meglio le funzioni. Il risultato e un set di API facilmente configurabile, maneggevole, e altamente personalizzabile, nonche, essendo basato appunto su JSON:API, facilmente comunicabile e portabile.
Se poi vogliamo estendere ulteriormente le funzionalita del nostro progetto, prima di scrivere codice custom abbiamo a disposizione molti altri moduli:
- JSON:API Search API permette di effettuare richieste sugli indici di ricerca del sito tramite una modalita analoga a quella appena vista.
- Entity share sfrutta le JSON:API esposte per permettere la sincronizzazione dei contenuti di due siti Drupal.
- Commerce API integra le funzionalita richieste da Drupal Commerce sfruttando le JSON:API.
Questo elenco di moduli non e esaustivo, ma e comunque un buon punto di partenza per farsi un’idea piu completa sull’ecosistema JSON:API su Drupal.
Considerazioni finali
Qui ci siamo soffermati su JSON:API, ma questo non e l’unico modulo o ecosistema disponibile per ottenere il nostro scopo. E quello al momento piu completo e supportato, ma ci sono anche altre opzioni, oltre ovviamente al codice custom.
Nel core di Drupal abbiamo un altro modulo, RESTful Web Services, che per un po’ di tempo e stato il diretto concorrente di JSON:API per diventare lo standard de facto per questa casistica d’uso. Alla fine si e affermato JSON:API, principalmente per la semplicita con cui riesce a coprire la maggior parte degli use cases. JSON:API permette di esporre tutte le entita presenti sul sito senza praticamente effort aggiuntivo, mentre RESTful Web Services richiede una configurazione custom piu complessa, le opzioni per il filtering dei dati sono piu limitate e complicate da configurare, le richieste per le risorse sono meno strutturate rispetto a quelle di JSON:API, e le collection possono essere esposte solo previa configurazione di apposite viste. Insomma, un buon modulo, ma che rimane indietro su alcuni rispetto alla semplicita e flessibilita di JSON:API. D’altro canto, per specifici casi d’uso, come ad esempio operazioni con logiche custom o che non siano legate strettamente alle entita, RESTful Web Services offre un framework sicuramente piu flessibile da poter sfruttare, al costo appunto di una maggiore complessita generale.
GraphQL invece e supportato grazie a un modulo contrib. Non e quindi nel core, e dei tre e l’ultimo arrivato sulla scena. In generale, essendo basato appunto su GraphQL, ha delle ottime specifiche ben documentate, ma alcune cose sono meno agili, come le operazioni di scrittura e il filtro lato client sui contenuti, che invece JSON:API gestisce nativamente senza problemi. Il suo grande vantaggio e la possibilita di definire con precisione i dati che si vogliono ottenere, evitando il problema dell’overfetching tipico delle API REST.
