Come utilizzare il modulo Webform REST con Drupal 11: una guida pratica

Nell'ambiente in continua evoluzione dello sviluppo web, Drupal 11 si distingue come una delle piattaforme più robuste e flessibili per creare siti web e applicazioni dinamiche. La sua architettura modulare consente agli sviluppatori di personalizzare ed estendere le funzionalità core per soddisfare una vasta gamma di esigenze progettuali.

Una di queste estensioni è il modulo Webform REST, uno strumento potente che permette un'integrazione fluida tra Drupal e applicazioni esterne tramite API RESTful. Questa guida offre un'introduzione pratica all'uso del modulo Webform REST con Drupal 11, spiegandone l'installazione e la configurazione, e mostrando come interagirci in modo efficace.

---

Cosa imparerai

Questo articolo copre i seguenti argomenti:

• Panoramica del modulo Webform REST

• Moduli richiesti e dipendenze

• Installazione di Webform REST e REST UI

• Configurazione del modulo Webform REST

• Gestione del CORS

• Esecuzione di richieste API

• Comprensione dei payload di richiesta e risposta

---

Panoramica del modulo: Webform REST

Il modulo Webform REST estende le capacità di Webform di Drupal esponendo le funzionalità relative ai moduli tramite endpoint RESTful. Con esso, puoi eseguire operazioni come creare, visualizzare, aggiornare ed eliminare webform, oltre a inviare e recuperare dati dei moduli tramite richieste HTTP.

Questo modulo è particolarmente utile per integrare Drupal con piattaforme esterne come:

• Sistemi CRM

• Strumenti di email marketing

• Applicazioni mobili

• Servizi di terze parti

Abilitando queste integrazioni, è possibile ottimizzare i flussi di lavoro e centralizzare la raccolta dei dati, migliorando notevolmente l'efficienza complessiva della tua applicazione.

---

Prerequisiti

Per iniziare a usare Webform REST, assicurati di avere installato i seguenti moduli:

• Webform – per creare e gestire i moduli web

• REST UI – per configurare endpoint RESTful e permessi

• Webform REST – il modulo principale che fornisce le funzionalità API

---

Installazione di Webform REST e dipendenze

In questa guida utilizziamo Docker e Lando per gestire l'ambiente di sviluppo locale e Composer per la gestione delle dipendenze.

Per installare il modulo Webform REST, esegui il seguente comando:

$ lando composer require 'drupal/webform_rest:^4.0'

Per abilitare il modulo:

$ lando drush en webform_rest

Inoltre, abilita il modulo REST UI, che ti permette di configurare gli endpoint REST tramite l'interfaccia di amministrazione:

$ lando drush en restui

In alternativa, puoi attivare questi moduli tramite l'interfaccia di amministrazione:
/admin/modules

---

Configurazione del modulo Webform REST

Una volta abilitati i moduli richiesti, vai alla pagina di configurazione REST:

Percorso: /admin/config/services/rest

Abilita le seguenti risorse REST:

• Webform Submission

• Webform Elements

• Webform Submit

Queste risorse forniscono gli endpoint essenziali per interagire con i moduli e i loro dati tramite REST.

È necessario selezionare almeno un metodo di autenticazione, nel nostro caso "cookie".

Per consentire agli utenti non autenticati di inviare richieste tramite il webform, devi concedere i permessi appropriati al ruolo Anonymous. In particolare, permetti loro di effettuare richieste POST alla risorsa REST Webform Submit.

Questa autorizzazione può essere configurata accedendo a:
/admin/people/permissions

Nella sezione “RESTful Web Services”, seleziona la casella per “Access POST on Webform Submit resource” per l'utente Anonymous. Questo garantisce che utenti o sistemi esterni senza autenticazione possano inviare con successo dati al tuo sito Drupal tramite la Webform REST API.

Una parola sul CORS

Se intendi effettuare richieste da un dominio diverso da quello dell'installazione della tua applicazione, è probabile che tu incontri un problema CORS come questo:

Comprendere e configurare il CORS in Drupal 11

CORS (Cross-Origin Resource Sharing) è un meccanismo di sicurezza fondamentale implementato dai browser per controllare come le risorse vengono accessibili tra origini diverse—dove un'origine è definita come una combinazione di dominio, protocollo e porta.

In termini semplici, il CORS consente ai server di specificare quali domini esterni sono autorizzati ad accedere a determinate risorse tramite richieste basate su browser. Senza una corretta configurazione del CORS, i browser applicano la Same-Origin Policy, che blocca l'accesso alle risorse da origini diverse da quella che ha servito la pagina web.

---

Configurare il CORS in Drupal 11

Drupal 11 gestisce le impostazioni CORS tramite il file services.yml, in particolare nella sezione cors.config. Per impostazione predefinita, questa configurazione è disabilitata, il che significa che le richieste cross-origin verranno bloccate se non esplicitamente consentite.

Per abilitare il CORS per i client esterni—come frontend JavaScript o app mobili—è necessario modificare la configurazione nel file services.yml. Ecco un esempio di configurazione permissiva per sviluppo o test:

cors.config:
    enabled: true
    allowedHeaders: ['x-csrf-token','authorization','content-type','accept','origin','x-requested-with', 'access-control-allow-origin','x-allowed-header','*']
    allowedMethods: ['*']
    allowedOrigins: ['*']
    exposedHeaders: false
    maxAge: false
    supportsCredentials: true

Configurare services.local.yml nello sviluppo locale

Nella maggior parte delle configurazioni di sviluppo locale Drupal, troverai un file chiamato services.local.yml. Questo file è specificamente pensato per sovrascrivere le configurazioni del file principale services.yml. Pertanto, eventuali modifiche effettuate in services.yml potrebbero essere ignorate se esistono impostazioni in conflitto o incomplete in services.local.yml.

Per garantire che la tua configurazione CORS venga applicata correttamente, assicurati di replicare o modificare le impostazioni in services.local.yml di conseguenza.

Svuotare la cache dopo la configurazione

Dopo aver aggiornato i file di configurazione YAML, svuota la cache di Drupal per applicare le modifiche:

$ lando drush cr

L'indentazione YAML è importante

Fai attenzione all'indentazione YAML, poiché è una delle cause più comuni di problemi di configurazione. Anche un solo spazio o tab errato può far ignorare le impostazioni—portando a ore di debug inutile. Se le modifiche non hanno effetto, ricontrolla prima l'indentazione.

---

Utilizzare il modulo Webform REST

Una volta configurato tutto, puoi iniziare a inviare moduli tramite REST. Il processo prevede l'invio di una richiesta POST all'endpoint Webform REST insieme alle intestazioni e al payload richiesti.

Endpoint

POST /webform_rest/submit

Intestazione richiesta

Content-Type: application/json

Esempio: invio di un modulo con Axios

Ecco un esempio di richiesta Axios in JavaScript per inviare dati di un modulo:

 const response = await axios.post('http://yoursite.lndo.site/webform_rest/submit', {
    "webform_id": "some_rest_form",
    "name": "Ivan Abramenko",
    "email": "levmyshkin89@gmail.com",
  }, {
    headers: {
    "Content-Type": 'application/json',
    },
  });

Questo esempio mostra come effettuare una richiesta POST usando Axios, ma puoi utilizzare anche altre librerie o framework HTTP per effettuare la richiesta.

Il payload della richiesta è composto principalmente da webform_id, che è il machine name del modulo di destinazione, e dai suoi campi registrati.

{
   "webform_id": "some_rest_form",
   "name": "Ivan Abramenko",
   "email": "levmyshkin89@gmail.com"
}

Il payload della risposta di un invio riuscito è composto dai seguenti campi:

• sid, l'identificatore univoco dell'invio registrato
• confirmation_url, l'URL di conferma dell'invio
• confirmation_message, il messaggio di conferma
• confirmation_title, il titolo del messaggio di conferma

{
   "sid": "ae8c3bd4-91a2-5c17-a264-59c86157457b",
   "confirmation_type": "inline",
   "confirmation_url": "",
   "confirmation_message": "Solo un messaggio di conferma",
   "confirmation_title": "Un titolo di conferma"
}

Inoltre, abbiamo accesso anche ai messaggi di validazione generati da Webform stesso. Ad esempio, se un campo obbligatorio non viene inviato, riceviamo la seguente risposta:

{
   "message": "I dati inviati contengono errori di validazione.",
   "error": {
       "email": "Il campo email è obbligatorio."
   }
}

Gestire la risposta dell’API

Con i dati della risposta restituiti dall'API, puoi fornire in modo programmatico feedback agli utenti—come conferme di successo, errori di validazione o fallimenti nell'invio. Personalizzare queste risposte migliora l'esperienza utente e garantisce chiarezza durante il processo di interazione.

Che tu stia integrando il modulo con un framework frontend o con un'app mobile, gestire correttamente la risposta dell'API è fondamentale per offrire un'esperienza fluida e intuitiva.

---

Conclusione

Il modulo Webform REST per Drupal 11 offre una soluzione potente e flessibile per interagire con i moduli web tramite API RESTful. Consentendo alle applicazioni esterne di inviare e manipolare i dati dei moduli, amplia notevolmente le capacità di integrazione di Drupal—rendendolo ideale per architetture web moderne che si basano su approcci decoupled o headless.

In questo articolo, abbiamo esplorato:

• Un'introduzione al modulo Webform REST

• Installazione e configurazione passo per passo

• Come inviare dati tramite API usando un esempio pratico

Sebbene questa guida si sia concentrata sull’invio dei moduli, il modulo Webform REST supporta ulteriori operazioni non trattate qui, tra cui:

• Richieste PATCH per aggiornare invii esistenti

• Richieste GET per recuperare dati degli invii o elencare i campi del modulo

• Personalizzazioni aggiuntive per autenticazione e controllo degli accessi

Questi casi d'uso avanzati saranno esplorati in futuri tutorial.