Comment utiliser le module Webform REST avec Drupal 11 : un guide pratique

Dans le paysage en constante évolution du développement web, Drupal 11 se distingue comme l’une des plateformes les plus robustes et flexibles pour créer des sites web dynamiques et des applications. Son architecture modulaire permet aux développeurs de personnaliser et d’étendre les fonctionnalités de base afin de répondre à une large gamme de besoins de projets.

Une extension notable est le module Webform REST, un outil puissant qui permet une intégration fluide entre Drupal et des applications externes via des API RESTful. Ce guide propose une introduction pratique à l’utilisation du module Webform REST avec Drupal 11, en détaillant son installation, sa configuration, et en montrant comment interagir efficacement avec lui.

---

Ce que vous apprendrez

Cet article couvre les sujets suivants :

• Présentation du module Webform REST

• Modules requis et dépendances

• Installation de Webform REST et REST UI

• Configuration du module Webform REST

• Gestion du CORS

• Effectuer des requêtes API

• Compréhension des payloads de requête et de réponse

---

Présentation du module : Webform REST

Le module Webform REST étend les capacités des formulaires Drupal Webform en exposant leurs fonctionnalités via des points d’accès RESTful. Avec ce module, vous pouvez créer, consulter, modifier, supprimer des formulaires web, ainsi que soumettre et récupérer des données de formulaire via des requêtes HTTP.

Ce module est particulièrement utile pour intégrer Drupal avec des plateformes externes telles que :

• Des systèmes CRM

• Des outils de marketing par email

• Des applications mobiles

• Des services tiers

Ces intégrations permettent de rationaliser les flux de travail et de centraliser la collecte de données, améliorant ainsi considérablement l’efficacité globale de votre application.

---

Prérequis

Pour commencer avec Webform REST, assurez-vous d’avoir installé les modules suivants :

• Webform – pour créer et gérer des formulaires web

• REST UI – pour configurer les points d’accès RESTful et les permissions

• Webform REST – le module principal fournissant la fonctionnalité API

---

Installation de Webform REST et dépendances

Dans ce guide, nous utilisons Docker et Lando pour gérer l’environnement de développement local, ainsi que Composer pour la gestion des dépendances.

Pour installer le module Webform REST, exécutez la commande suivante :

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

Pour activer le module :

$ lando drush en webform_rest

Activez également le module REST UI, qui vous permet de configurer les points d’accès REST via l’interface d’administration :

$ lando drush en restui

Vous pouvez aussi activer ces modules via l’interface d’administration :
/admin/modules

---

Configuration du module Webform REST

Une fois les modules requis activés, rendez-vous sur la page de configuration REST :

Chemin : /admin/config/services/rest

Activez les ressources REST suivantes :

• Soumission Webform

• Éléments Webform

• Soumettre Webform

Ces ressources fournissent les points d’accès essentiels pour interagir avec les formulaires et leurs données via REST.

Il est nécessaire de sélectionner au moins une méthode d’authentification, dans notre cas, « cookie ».

Pour permettre aux utilisateurs non authentifiés de soumettre des requêtes via le formulaire web, vous devez attribuer la permission appropriée au rôle Utilisateur anonyme. Plus précisément, autorisez-les à faire des requêtes POST sur la ressource REST Soumettre Webform.

Cette permission se configure via :
/admin/people/permissions

Sous la section « RESTful Web Services », cochez la case « Accès POST sur la ressource Soumettre Webform » pour le rôle Utilisateur anonyme. Cela garantit que les utilisateurs externes ou systèmes sans authentification peuvent soumettre des données avec succès sur votre site Drupal via l’API Webform REST.

Un mot sur le CORS

Si vous faites des requêtes depuis un domaine différent de celui de votre application, vous rencontrerez probablement un problème CORS comme celui-ci :

Comprendre et configurer le CORS dans Drupal 11

CORS (Cross-Origin Resource Sharing) est un mécanisme de sécurité important implémenté par les navigateurs pour contrôler comment les ressources sont accessibles entre différentes origines — où une origine est définie par la combinaison de domaine, protocole et port.

En termes simples, CORS permet aux serveurs de spécifier quels domaines externes peuvent accéder à certaines ressources via des requêtes basées sur le navigateur. Sans politique CORS configurée correctement, les navigateurs appliquent la Same-Origin Policy qui bloque l’accès aux ressources depuis toute origine autre que celle qui a servi la page web.

---

Configurer le CORS dans Drupal 11

Drupal 11 gère les réglages CORS via le fichier services.yml, notamment sous la section cors.config. Par défaut, cette configuration est désactivée, ce qui signifie que les requêtes cross-origin seront bloquées à moins d’être explicitement autorisées.

Pour activer le CORS pour des clients externes — comme des frontends JavaScript ou des applications mobiles — vous devez modifier la configuration dans votre fichier services.yml. Voici un exemple d’une configuration permissive pour un environnement de développement ou de 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

Configurer services.local.yml en développement local

Dans la plupart des configurations locales Drupal, vous disposez d’un fichier nommé services.local.yml destiné à surcharger les configurations du fichier principal services.yml. Ainsi, toute modification dans services.yml peut être ignorée si des réglages conflictuels ou incomplets existent dans services.local.yml.

Pour garantir que votre configuration CORS soit bien prise en compte, veillez à répliquer ou modifier les réglages correspondants dans services.local.yml.

Vider le cache après la configuration

Après avoir modifié vos fichiers YAML, videz le cache Drupal pour appliquer les changements :

$ lando drush cr

L’importance de l’indentation YAML

Faites très attention à l’indentation YAML, cause fréquente de problèmes de configuration. Une simple erreur d’espace ou de tabulation peut entraîner l’ignorance des réglages — ce qui conduit à des heures de débogage inutiles. Si vos changements ne prennent pas effet, vérifiez d’abord l’indentation.

---

Utiliser le module Webform REST

Une fois tout configuré, vous pouvez commencer à soumettre des formulaires via REST. Le processus consiste à envoyer une requête POST au point d’accès Webform REST avec les en-têtes et la charge utile nécessaires.

Point d’accès

POST /webform_rest/submit

En-tête requis

Content-Type: application/json

Exemple : soumettre un formulaire avec Axios

Voici un exemple de requête Axios en JavaScript pour soumettre des données de formulaire :

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

Cet exemple montre comment faire une requête POST avec Axios, mais vous pouvez utiliser d’autres bibliothèques ou frameworks HTTP pour effectuer la requête.

La charge utile de la requête contient principalement le webform_id, qui est le nom machine du formulaire cible, ainsi que ses champs enregistrés.

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

La charge utile de la réponse d’une soumission réussie contient les champs suivants :

• sid, identifiant unique de la soumission enregistrée
• confirmation_url, URL de confirmation de la soumission
• confirmation_message, message de confirmation
• confirmation_title, titre du message de confirmation

{
   "sid": "ae8c3bd4-91a2-5c17-a264-59c86157457b",
   "confirmation_type": "inline",
   "confirmation_url": "",
   "confirmation_message": "Just a confirmation message",
   "confirmation_title": "A confirmation title"
}

De plus, vous avez accès aux messages de validation générés par Webform lui-même. Par exemple, si un champ obligatoire n’est pas soumis, vous recevez la réponse suivante :

{
   "message": "Submitted Data contains validation errors.",
   "error": {
       "email": "The email field is mandatory."
   }
}

Gérer la réponse de l’API

Avec les données retournées par l’API, vous pouvez fournir un retour programmatique aux utilisateurs — comme des confirmations de succès, des erreurs de validation ou des échecs de soumission. Adapter ces réponses améliore l’expérience utilisateur et assure une interaction claire.

Que vous intégriez le formulaire avec un framework frontend ou une application mobile, gérer efficacement la réponse API est clé pour offrir une expérience fluide et intuitive.

---

En conclusion

Le module Webform REST pour Drupal 11 propose une solution puissante et flexible pour interagir avec les formulaires via des API RESTful. En permettant aux applications externes de soumettre et manipuler les données de formulaire, il étend considérablement les capacités d’intégration de Drupal — idéal pour les architectures modernes déconnectées ou headless.

Dans cet article, nous avons exploré :

• Une introduction au module Webform REST

• Une installation et configuration étape par étape

• Comment soumettre des données via l’API avec un exemple pratique

Bien que ce guide se concentre sur la soumission de formulaires, le module Webform REST prend en charge d’autres opérations non abordées ici, telles que :

• Requêtes PATCH pour mettre à jour des soumissions existantes

• Requêtes GET pour récupérer des données de soumission ou lister les champs d’un formulaire

• Personnalisation supplémentaire pour l’authentification et le contrôle d’accès

Ces cas d’usage avancés seront abordés dans des tutoriels futurs.