Drupal come backend: GraphQL, JSON:API, RESTful e il costoso errore nascosto nella scelta dell’API

Una volta un CTO mi ha chiesto, a metà di una riunione di pianificazione su Drupal decoupled: “Quindi quale API dovremmo usare?”

La stanza è rimasta in silenzio per un secondo. Il frontend voleva GraphQL. Il backend voleva JSON:API. Un fornitore di integrazione aveva già dato per scontato REST. Il product owner voleva solo che l’app mobile smettesse di aspettare i rilasci del sito web.

Quella piccola domanda di solito sembra tecnica. Non lo è. È una domanda di governance, una domanda di budget e a volte una domanda di assunzioni travestita con una felpa da sviluppatore.

Drupal può essere un backend molto capace per prodotti decoupled. Ha già contenuti strutturati, ruoli, permessi, workflow, revisioni, traduzioni, gestione dei media, tassonomia e un ecosistema maturo di moduli. La parte scomoda è decidere come quel contenuto lascia Drupal. Il core di Drupal ha supporto nativo per JSON:API, GraphQL è disponibile tramite un modulo contribuito, e il modulo RESTful Web Services di Drupal rimane un’opzione per endpoint personalizzati in stile risorsa. La documentazione decoupled di Drupal lo dice chiaramente: JSON:API è nel core, GraphQL è contribuito, e Drupal può esporre contenuti a un frontend esterno tramite API.

Eppure i team continuano a scegliere male.

Scelgono GraphQL perché suona moderno. Scelgono REST perché tutti lo hanno usato. Scelgono JSON:API perché è lì. Nessuna di queste è una strategia.

Ecco la versione più netta: per la maggior parte delle piattaforme di contenuto basate su Drupal, JSON:API dovrebbe essere il punto di partenza predefinito. GraphQL dovrebbe essere guadagnato. REST dovrebbe essere riservato ai casi in cui gli altri due sono troppo ampi o troppo prescrittivi.

Questo darà fastidio ad alcune persone. Bene.

Inizia dal vincitore noioso: JSON:API

JSON:API è noioso nel miglior modo possibile.

Il modulo JSON:API del core di Drupal implementa la specifica JSON:API per le entità Drupal. Offre un modo senza configurazione e prescrittivo per esporre operazioni CRUD per i contenuti del sito, ed è integrato con Entity API, Field API, caching, autenticazione e sistemi di autorizzazione di Drupal.

Quella frase contiene la parte che dovrebbe interessare ai dirigenti: modulo del core.

Il core conta. Il core di solito significa meno sorprese dai fornitori, pianificazione della manutenzione più semplice, una postura di sicurezza più chiara e meno rischio del tipo “ci serve quell’unico contractor che capisce il layer API personalizzato”. La documentazione JSON:API di Drupal dice che il modulo espone API intorno a tipi di entità e bundle, supporta filtri, include, paginazione, ordinamento, revisioni, traduzioni, GET, POST, PATCH, DELETE, upload di file e personalizzazione delle risorse tramite eventi.

Un esempio pratico: immagina una società media con articoli, autori, argomenti, teaser per landing page e immagini. Il team frontend ha bisogno di pagine articolo in Next.js. L’app mobile ha bisogno dello stesso corpo dell’articolo, dell’immagine hero, del nome dell’autore e degli argomenti correlati. JSON:API può esporre quelle entità Drupal senza costringere il team backend a inventare un linguaggio API da zero. Le risorse correlate possono essere incorporate tramite include, e le collezioni possono essere filtrate o paginate.

Il payload è bello? A volte. A volte sembra progettato da un comitato dopo un pranzo lungo.

Ma anche questo è il punto. JSON:API è una specifica, non il gusto personale di uno sviluppatore. Il sito ufficiale di JSON:API lo descrive come una specifica per costruire API in JSON, con convenzioni condivise che riducono le discussioni sulla forma della risposta e aiutano i team a usare strumenti generali. Il suo media type è application/vnd.api+json, e la versione 1.1 è stata finalizzata il 30 settembre 2022.

Qui c’è un vantaggio gestionale nascosto. Un formato di risposta standardizzato significa che l’onboarding dipende meno dalla conoscenza tribale. Un nuovo sviluppatore frontend potrebbe comunque imprecare contro la struttura annidata data, attributes e relationships. Va bene. Almeno sta imprecando contro qualcosa di documentato.

Il tranello che nessuno vuole menzionare

JSON:API espone il modello di contenuto di Drupal in modo piuttosto diretto. Questo può essere un punto di forza, specialmente quando Drupal è la fonte editoriale di verità. Può anche far trapelare troppo della struttura interna di Drupal nel frontend.

Se il tuo modello di contenuto è pulito, JSON:API sembra efficiente. Se il tuo modello di contenuto è un museo di vecchi compromessi, JSON:API rende visibile il disordine.

Ho visto content type “Article” con campi come field_new_body_2021, field_mobile_summary, field_legacy_related e field_do_not_use. JSON:API non trasforma magicamente tutto questo in una product API elegante. Espone il modello che hai davvero. Un po’ crudele, forse. Però utile.

La documentazione di Drupal chiarisce anche un confine: JSON:API gestisce CRUD orientato alle entità, ma regole di business come login, reset della password e creazione dell’account sono fuori dal compito di JSON:API. Se la tua applicazione ha bisogno di azioni di dominio come “approva fornitore”, “calcola preventivo di rinnovo” o “invia reclamo”, non forzarle dentro endpoint di entità di contenuto solo perché il modulo è comodo.

Quella strada diventa brutta in fretta.

GraphQL sembra elegante perché sposta il dolore

GraphQL è seducente. Il frontend chiede esattamente i campi che vuole. La risposta ha la stessa forma della query. Ha uno schema tipizzato. Sembra progettato per frontend basati su componenti perché, francamente, lo è stato. Il sito ufficiale di GraphQL descrive GraphQL come un linguaggio di query open source e un runtime server-side per API con uno schema fortemente tipizzato, e mostra il client che chiede campi selezionati invece di ricevere una risposta server fissa.

Per i team frontend, questo è un miglioramento reale.

Prendi una homepage composta da componenti: hero, articoli in evidenza, eventi, slot sponsor, navigazione, avvisi regionali. Con REST, il frontend potrebbe chiamare diversi endpoint. Con JSON:API, potrebbe richiedere una collezione e includere risorse correlate, ma la struttura segue comunque le relazioni tra entità. Con GraphQL, la query può sembrare più vicina allo schermo. Questo conta quando i team rilasciano rapidamente superfici di prodotto.

Il modulo GraphQL di Drupal consente agli sviluppatori di creare ed esporre uno schema GraphQL per Drupal 10 e 11. È costruito intorno a webonyx/graphql-php, supporta la specifica ufficiale GraphQL, include GraphiQL in /graphql/explorer e offre agli sviluppatori plugin data producer più codice personalizzato per il lavoro sullo schema.

Leggi attentamente la formulazione: “creare ed esporre”.

L’attuale modulo GraphQL di Drupal non è uno specchio magico che riflette semplicemente ogni campo Drupal in un’API ordinata. Drupal.org dice che la vecchia versione 3.x generava automaticamente uno schema dalle entità Drupal ed esponeva i dettagli di Drupal tramite l’API, mentre la 4.x lascia il design dello schema allo sviluppatore, così che gli internals di Drupal possano essere nascosti. La stessa pagina dice che la 4.x richiede allo sviluppatore di configurare e mappare lo schema.

Questa non è una nota a piè di pagina. È la fattura.

GraphQL può darti un contratto pulito tra prodotto e storage dei contenuti. Ma qualcuno deve progettare quel contratto. Qualcuno deve mantenerlo quando gli editor aggiungono campi, quando il design system cambia, quando arriva la personalizzazione, quando il legale chiede logica di consenso regionale, quando il team mobile ha bisogno della sincronizzazione offline.

In realtà, questo è troppo gentile. Qualcuno deve possederlo. L’ownership è la voce mancante in molte proposte GraphQL.

Quando GraphQL vale il costo

GraphQL ha senso quando l’API è un prodotto a sé.

Una grande università con decine di micrositi, un’app mobile per studenti, digital signage, profili dei docenti, cataloghi dei corsi e un design system può beneficiare di un layer GraphQL. I consumatori sono vari. Il grafo dei contenuti è profondo. I team frontend hanno bisogno di accesso selettivo. L’organizzazione potrebbe volere un contratto API che nasconda le eccentricità dei bundle Drupal.

GraphQL si adatta anche quando Drupal è solo una fonte tra molte. Forse i contenuti arrivano da Drupal, i prezzi da un ERP, la disponibilità da un motore di prenotazione e i diritti degli utenti da un CRM. GraphQL può presentare ai client uno schema coerente mentre i resolver recuperano dati da sistemi diversi. Il modello GraphQL è stato costruito intorno a uno schema fortemente tipizzato e a una forma di risposta specificata dal client, ed è esattamente per questo che funziona bene in questo tipo di layer di composizione.

Ma per un normale sito marketing con un frontend headless? Sarei scettico. Persino leggermente infastidito.

Se il vero bisogno è “React dovrebbe leggere articoli da Drupal”, GraphQL potrebbe essere una festa in maschera. Spenderai soldi di architettura per evitare di imparare include e filtri di JSON:API. Peggio, potresti creare un layer API su misura che capiscono solo due sviluppatori.

La pagina del progetto Drupal GraphQL riporta che le release stabili sono coperte dalla policy sugli avvisi di sicurezza di Drupal ed elenca release recenti per Drupal 10 e 11, inclusa la 8.x-4.14 rilasciata il 29 aprile 2026 e una beta 5.0.0 per Drupal 10.4 e 11. Questo è sano. Non elimina il lavoro di design.

Un modulo contribuito può essere maturo e comunque essere il default sbagliato.

RESTful Web Services: vecchio, utile e di solito abusato

REST è diventato una di quelle parole che significano qualunque cosa serva a chi parla. A volte significa HTTP pulito orientato alle risorse. A volte significa “restituiamo JSON da un controller”. A volte significa “il fornitore ci ha dato un endpoint e un PDF”.

La tesi di Roy Fielding ha introdotto REST come stile architetturale per sistemi ipermediali distribuiti, con vincoli come separazione client-server, comunicazione stateless, cache, interfaccia uniforme, sistemi a livelli e code-on-demand opzionale. Quell’idea originale è più rigorosa di molto di ciò che nei piani di progetto viene chiamato REST.

Il modulo RESTful Web Services di Drupal è utile perché può esporre risorse con metodi specifici, formati di serializzazione e autenticazione. Il materiale di studio Drupal descrive risorse REST per entità, supporto per metodi come GET, POST, PATCH e DELETE, serializzazione JSON o XML, e autenticazione tramite Basic Auth, cookie o altri moduli come OAuth. Nota anche che i metodi non sicuri richiedono un header di richiesta X-CSRF-Token.

Questo rende REST adatto a lavori di integrazione ristretti.

Un provider di pagamenti invia lo stato della transazione a Drupal. Un sistema di magazzino recupera un elenco di manuali prodotto aggiornati. Un portale partner ha bisogno di un endpoint accuratamente modellato per asset approvati. Una vecchia app mobile si aspetta già /api/v1/articles/{id} e non può essere riscritta questo trimestre.

REST ti dà controllo. Ti dà anche la sindrome della pagina bianca.

A differenza di JSON:API, dove le convenzioni sono già scelte, un endpoint REST personalizzato richiede decisioni: forma dell’URL, formato della risposta, formato degli errori, stile di paginazione, sintassi dei filtri, versioning, autenticazione, header di cache, documentazione, policy di deprecazione. OpenAPI può aiutare a documentare quella superficie, e la OpenAPI Specification è un modo standard e indipendente dal linguaggio per descrivere API HTTP, così che esseri umani e computer possano comprenderle senza leggere il codice sorgente.

Comunque, devi fare le scelte.

E quelle scelte restano. Un endpoint sciatto progettato nella seconda settimana può perseguitare il prodotto per anni perché qualche versione dell’app in circolazione dipende ancora da esso.

La decisione non è “quale API è la migliore?”

Questo inquadramento è pigro. Mi dispiace, ma lo è.

La domanda migliore è: quale tipo di accoppiamento può permettersi la tua organizzazione?

JSON:API accoppia i consumatori al modello di entità di Drupal. Questo è spesso accettabile quando Drupal è il principale sistema di contenuti e il frontend è un layer di presentazione sostitutivo. La ricompensa è velocità e meno invenzione backend.

GraphQL accoppia i consumatori a uno schema progettato dal tuo team. Fatto bene, quello schema nasconde Drupal ed esprime il dominio del prodotto. Fatto male, diventa un secondo modello CMS mantenuto nel codice.

REST accoppia i consumatori a endpoint personalizzati. Questo è eccellente per integrazioni specifiche e pericoloso per la distribuzione ampia di contenuti, perché ogni endpoint diventa un prodotto in miniatura con la propria coda di manutenzione.

Ecco la versione che metterei davanti a un executive steering group.

Le tabelle sono un po’ sterili, ma questa fa risparmiare riunioni.

Cosa dovrebbero osservare i project manager

La scelta dell’API cambia il piano di progetto più di quanto le persone ammettano.

Con JSON:API, il percorso critico è il content modeling. Se il modello di contenuto è ragionato, il lavoro sull’API può procedere rapidamente. Se il modello di contenuto è caotico, lo sviluppo frontend rallenta perché ogni query espone un altro compromesso editoriale. Metti attenzione senior su naming dei campi, pattern di paragraph riutilizzabili, relazioni media, tassonomia e permessi prima che il team frontend inizi a collegare le pagine.

Con GraphQL, il percorso critico è la ownership dello schema. Chi progetta lo schema? Chi revisiona i breaking change? Chi scrive i resolver? Chi gestisce problemi di performance come query annidate che innescano troppi caricamenti backend? Il modulo Drupal GraphQL offre strumenti e punti di estensione, inclusi plugin data producer e GraphiQL, ma non elimina la necessità di disciplina ingegneristica backend.

Con REST, il percorso critico è la disciplina del contratto. Ogni endpoint ha bisogno di documentazione, test, regole di autenticazione, semantica degli errori e una storia di versioning. REST sembra economico quando viene costruito il primo endpoint. Il quinto endpoint dice la verità.

Un’altra cosa. L’autenticazione è spesso sottovalutata. Drupal JSON:API è legato ai sistemi di autenticazione e autorizzazione di Drupal, e REST può usare provider di autenticazione come Basic Auth e cookie, con OAuth comunemente aggiunto tramite moduli contribuiti. La documentazione di Lupus Decoupled Drupal indica Simple OAuth come modo per autenticare richieste API tramite token in configurazioni decoupled.

Non lasciarlo allo sprint prima del lancio. Quello sprint è già maledetto.

Performance: l’argomento che tutti semplificano

I fan di GraphQL dicono che evita l’over-fetching. Vero. I fan di JSON:API dicono che gli include riducono i round trip. Anche vero. I fan di REST dicono che il caching HTTP è diretto. Ancora vero.

Ora la parte spiacevole: tutti e tre possono essere veloci, e tutti e tre possono essere lenti.

GraphQL può ridurre la dimensione del payload, ma query annidate complesse possono punire il backend se i resolver sono trascurati. JSON:API può usare il response caching di Drupal e gli include, ma i payload possono essere verbosi. REST può mappare bene sul caching HTTP, ma gli endpoint personalizzati spesso dimenticano la cacheability finché non iniziano i performance test. I vincoli REST di Fielding includono la cache perché la cache può ridurre traffico di rete e latenza, ma dati obsoleti e invalidazione della cache restano compromessi reali. La documentazione JSON:API di Drupal collega esplicitamente il modulo al response caching di Drupal, mentre il modulo GraphQL è categorizzato su Drupal.org sotto Decoupled, Developer tools e Performance.

Quindi no, GraphQL non è automaticamente “l’opzione performance”.

Il primo guadagno di performance di solito è un content modeling migliore. Il secondo è una strategia di cache. Il terzo è evitare comportamenti sciocchi del client, come chiamare lo stesso endpoint dodici volte perché nessuno ha scritto un data access layer.

Glamour? No. Efficace? Sì.

Un framework di selezione diretto

Se stessi consigliando un founder o un CTO, partirei da questa sequenza.

Primo, usa le normali pagine renderizzate di Drupal a meno che tu non abbia un motivo per decoupling. Il decoupling aggiunge complessità di hosting, preview, routing, cache, deployment, autenticazione e debugging. La documentazione decoupled di Drupal distingue Drupal standard da Drupal decoupled notando che il layout si sposta nel frontend e il backend espone contenuti tramite API. Questo spostamento non è gratuito.

Secondo, se stai facendo decoupling principalmente per un frontend moderno, inizia con JSON:API. Costruisci una pagina reale, non una demo. Includi media, menu o navigazione, contenuto correlato, esigenze di preview, autenticazione se richiesta e comportamento della cache. Imparerai di più da una pagina brutta che da sei diagrammi di architettura.

Terzo, passa a GraphQL solo quando l’esperienza dei consumatori giustifica il lavoro sullo schema. Buone ragioni includono più consumatori frontend, la necessità di nascondere gli internals di Drupal, grafi di contenuto complessi o aggregazione tra sistemi. Cattive ragioni includono “al nostro sviluppatore frontend piace Apollo” e “nel deck per gli investitori c’è scritto GraphQL”.

Quarto, usa REST per integrazioni che richiedono confini stretti. Un endpoint personalizzato per un export verso un partner può essere pulito. Un’intera piattaforma di contenuto fatta di endpoint costruiti a mano può diventare un cassetto pieno di chiavi senza etichetta.

E ripulisci il modello Drupal. Per favore. Nessun layer API può salvare completamente un modello di contenuto che nessuno possiede.

La politica del “future-proof”

Ai dirigenti piace l’espressione “future-proof”. Capisco perché. Nessuno vuole approvare la ricostruzione di un backend e sentire, diciotto mesi dopo, che l’API scelta ha messo l’azienda in un angolo.

Ma prepararsi al futuro di solito riguarda meno la scelta dell’API più appariscente e più la decisione di dove è consentito che avvenga il cambiamento.

JSON:API dice: “Il modello di Drupal è il contratto.” È onesto e veloce.

GraphQL dice: “Il nostro schema di prodotto è il contratto.” È potente e costoso.

REST dice: “Questo endpoint è il contratto.” È preciso e facile da moltiplicare fino a diventare un problema di manutenzione.

Non esiste un vincitore universale. Esiste solo l’adattamento.

Il mio bias è semplice: inizia con la cosa meno personalizzata che può supportare il prodotto. In Drupal, questo di solito significa JSON:API. Aggiungi GraphQL quando puoi nominare l’owner e il budget. Aggiungi REST quando l’integrazione è abbastanza specifica da meritare la propria porta.

La scelta peggiore è quella fatta per moda, perché la moda non si presenta mai alla manutenzione.

Cerchi la società di sviluppo Drupal numero 1 sul mercato? L’hai appena trovata.

Siamo la migliore agenzia digitale focalizzata su Drupal, creata per fornire piattaforme veloci, sicure e scalabili, senza compromessi. Da nuovi sviluppi e redesign a migrazioni e supporto a lungo termine, i nostri esperti Drupal consegnano risultati di livello enterprise con attenzione da boutique agency.

Prenota una call oggi e trasformiamo la tua roadmap Drupal in una realtà ad alte prestazioni.