Cómo usar el módulo REST Webform con Drupal 11: una guía práctica

En el panorama siempre cambiante del desarrollo web, Drupal 11 se destaca como una de las plataformas más robustas y flexibles para crear sitios web y aplicaciones dinámicas. Su arquitectura modular permite a los desarrolladores personalizar y extender las funcionalidades principales para adaptarse a una amplia variedad de necesidades de proyecto.

Una de esas extensiones es el módulo Webform REST, una herramienta potente que permite la integración fluida entre Drupal y aplicaciones externas mediante APIs RESTful. Esta guía ofrece una introducción práctica al uso del módulo Webform REST con Drupal 11, mostrando su instalación, configuración y cómo interactuar con él de manera eficaz.

---

Qué aprenderás

Este artículo cubre los siguientes temas:

• Resumen del módulo Webform REST

• Módulos y dependencias requeridas

• Instalación de Webform REST y REST UI

• Configuración del módulo Webform REST

• Manejo de CORS

• Realización de solicitudes API

• Comprensión de los datos enviados y recibidos (payloads)

---

Resumen del módulo: Webform REST

El módulo Webform REST extiende las capacidades de Webform en Drupal exponiendo la funcionalidad de los formularios a través de endpoints RESTful. Con él, puedes realizar operaciones como crear, ver, actualizar y eliminar formularios web, así como enviar y recuperar datos de formularios a través de solicitudes HTTP.

Este módulo es especialmente útil para integrar Drupal con plataformas externas como:

• Sistemas CRM

• Herramientas de email marketing

• Aplicaciones móviles

• Servicios de terceros

Al habilitar estas integraciones, puedes optimizar flujos de trabajo y centralizar la recopilación de datos, mejorando significativamente la eficiencia general de tu aplicación.

---

Prerrequisitos

Para comenzar con Webform REST, asegúrate de tener instalados los siguientes módulos:

• Webform – para crear y gestionar formularios web

• REST UI – para configurar endpoints RESTful y permisos

• Webform REST – el módulo principal que proporciona la funcionalidad API

---

Instalación de Webform REST y dependencias

En esta guía, utilizamos Docker y Lando para la gestión del entorno local de desarrollo y Composer para la gestión de dependencias.

Para instalar el módulo Webform REST, ejecuta el siguiente comando:

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

Para habilitar el módulo:

$ lando drush en webform_rest

Adicionalmente, habilita el módulo REST UI, que te permite configurar los endpoints REST desde la interfaz de administración:

$ lando drush en restui

Como alternativa, puedes activar estos módulos desde la interfaz de administración:
/admin/modules

---

Configuración del módulo Webform REST

Una vez habilitados los módulos necesarios, navega a la página de configuración REST:

Ruta: /admin/config/services/rest

Habilita los siguientes recursos REST:

• Webform Submission

• Webform Elements

• Webform Submit

Estos recursos proveen los endpoints esenciales para interactuar con los formularios y sus datos vía REST.

Es necesario seleccionar al menos un método de autenticación, en nuestro caso, "cookie".

Para permitir que usuarios no autenticados envíen solicitudes mediante el formulario web, debes otorgar los permisos apropiados al rol de usuario Anónimo. Específicamente, permite que realicen solicitudes POST al recurso REST Webform Submit.

Esta configuración se realiza navegando a:
/admin/people/permissions

En la sección “RESTful Web Services”, marca la casilla de “Access POST on Webform Submit resource” para el usuario anónimo. Esto asegura que usuarios o sistemas externos sin autenticación puedan enviar datos a tu sitio Drupal a través de la API Webform REST.

Una palabra sobre CORS

Si planeas realizar solicitudes desde un dominio diferente al de tu aplicación, probablemente te encuentres con un error de CORS como este:

Entendiendo y configurando CORS en Drupal 11

CORS (Cross-Origin Resource Sharing) es un mecanismo de seguridad fundamental implementado por los navegadores para controlar cómo se accede a los recursos entre diferentes orígenes—donde un origen se define como una combinación de dominio, protocolo y puerto.

En términos simples, CORS permite que los servidores especifiquen qué dominios externos tienen permitido acceder a ciertos recursos mediante solicitudes hechas desde navegadores. Sin una política CORS correctamente configurada, los navegadores aplican la Política de mismo origen (Same-Origin Policy), bloqueando el acceso a recursos desde cualquier origen distinto al que sirvió la página web.

---

Configurando CORS en Drupal 11

Drupal 11 gestiona la configuración de CORS a través del archivo services.yml, específicamente en la sección cors.config. Por defecto, esta configuración está deshabilitada, lo que significa que las solicitudes de origen cruzado serán bloqueadas a menos que se permitan explícitamente.

Para habilitar CORS para clientes externos—como frontends JavaScript o apps móviles—deberás modificar la configuración en tu archivo services.yml. Aquí tienes un ejemplo de configuración permisiva para desarrollo o pruebas:

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

Configurando services.local.yml en desarrollo local

En la mayoría de las instalaciones locales de Drupal, tendrás un archivo llamado services.local.yml. Este archivo está diseñado específicamente para sobrescribir configuraciones del archivo principal services.yml. Por lo tanto, cualquier cambio que realices en services.yml puede ser ignorado si existen configuraciones conflictivas o incompletas en services.local.yml.

Para asegurarte de que tu configuración de CORS se aplique correctamente, asegúrate de replicar o modificar los ajustes en services.local.yml según corresponda.

Borra la caché después de configurar

Después de actualizar tus archivos YAML de configuración, borra la caché de Drupal para aplicar los cambios:

$ lando drush cr

La indentación en YAML importa

Sé meticuloso con la indentación en YAML, ya que es una fuente común de problemas de configuración. Incluso un solo espacio o tabulador fuera de lugar puede causar que los ajustes sean ignorados—lo que lleva a horas de depuración innecesaria. Si tus cambios no surten efecto, revisa primero la indentación.

---

Uso del módulo Webform REST

Una vez que todo está configurado, puedes comenzar a enviar formularios vía REST. El proceso implica enviar una solicitud POST al endpoint REST de Webform junto con los encabezados y payload necesarios.

Endpoint

POST /webform_rest/submit

Encabezado requerido

Content-Type: application/json

Ejemplo: Enviar un formulario usando Axios

A continuación, un ejemplo de solicitud con Axios en JavaScript para enviar datos de un formulario:

 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',
    },
  });

Este ejemplo demuestra cómo hacer una solicitud POST usando Axios, pero puedes usar otras librerías o frameworks HTTP para realizar la solicitud.

El payload de la solicitud consiste principalmente en el webform_id, que es el nombre de máquina del formulario objetivo, y sus campos registrados.

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

El payload de respuesta de una sumisión exitosa contiene los siguientes campos:

• sid, el identificador único del registro de envío
• confirmation_url, la URL de confirmación de la sumisión
• confirmation_message, el mensaje de confirmación
• confirmation_title, el título del mensaje de confirmación

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

Adicionalmente, también tienes acceso a los mensajes de validación generados por Webform. Por ejemplo, si no se envía un campo obligatorio, se recibe la siguiente respuesta:

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

Manejo de la respuesta API

Con los datos de respuesta devueltos por la API, puedes proporcionar retroalimentación programática a los usuarios—como mensajes de confirmación de éxito, errores de validación o fallos de envío. Personalizar estas respuestas mejora la experiencia de usuario y garantiza claridad durante el proceso de interacción.

Ya sea que estés integrando el formulario con un framework frontend o una app móvil, gestionar la respuesta de la API de forma efectiva es clave para ofrecer una experiencia fluida e intuitiva.

---

En resumen

El módulo Webform REST para Drupal 11 ofrece una solución potente y flexible para interactuar con formularios web mediante APIs RESTful. Al permitir que aplicaciones externas envíen y manipulen datos de formularios, amplía considerablemente las capacidades de integración de Drupal—lo que lo hace ideal para arquitecturas web modernas que dependen de enfoques desacoplados (decoupled) o headless.

En este artículo hemos visto:

• Una introducción al módulo Webform REST

• Instalación y configuración paso a paso

• Cómo enviar datos a través de la API con un ejemplo práctico

Aunque esta guía se centró en la envío de formularios, el módulo Webform REST soporta operaciones adicionales que no se cubrieron aquí, incluyendo:

• Solicitudes PATCH para actualizar envíos existentes

• Solicitudes GET para recuperar datos de envíos o listar campos de formularios

• Personalización adicional para autenticación y control de acceso

Estos casos de uso avanzados se explorarán en futuros tutoriales.