Wie man das Webform REST-Modul mit Drupal 11 verwendet: Ein praktischer Leitfaden

In der sich ständig weiterentwickelnden Landschaft der Webentwicklung zeichnet sich Drupal 11 als eine der robustesten und flexibelsten Plattformen für den Aufbau dynamischer Websites und Anwendungen aus. Die modulare Architektur ermöglicht es Entwickler:innen, die Kernfunktionalität an die unterschiedlichsten Projektanforderungen anzupassen und zu erweitern.

Eine dieser Erweiterungen ist das Webform REST-Modul, ein leistungsstarkes Werkzeug, das eine nahtlose Integration zwischen Drupal und externen Anwendungen über RESTful APIs ermöglicht. Dieser Leitfaden bietet eine praxisnahe Einführung in die Nutzung des Webform REST-Moduls mit Drupal 11, einschließlich Einrichtung und Konfiguration sowie der effektiven Interaktion über die API.

---

Was Sie lernen werden

Dieser Artikel behandelt folgende Themen:

• Überblick über das Webform REST-Modul
• Benötigte Module und Abhängigkeiten
• Installation von Webform REST und REST UI
• Konfiguration des Webform REST-Moduls
• Umgang mit CORS
• API-Anfragen stellen
• Verstehen von Request- und Response-Payloads

---

Modulübersicht: Webform REST

Das Webform REST-Modul erweitert die Webform-Funktionalität von Drupal, indem es Formulare und formularbezogene Funktionen über RESTful-Endpunkte bereitstellt. Damit können Sie Vorgänge wie das Erstellen, Anzeigen, Aktualisieren und Löschen von Webformularen sowie das Absenden und Abrufen von Formulardaten per HTTP-Anfrage durchführen.

Dieses Modul ist besonders nützlich für die Integration von Drupal mit externen Plattformen wie:

• CRM-Systemen
• E-Mail-Marketing-Tools
• Mobilen Anwendungen
• Drittanbieter-Diensten

Mit diesen Integrationen lassen sich Workflows optimieren und die Datenerfassung zentralisieren, was die Effizienz Ihrer Anwendung erheblich steigert.

---

Voraussetzungen

Um mit Webform REST zu starten, stellen Sie sicher, dass Sie folgende Module installiert haben:

• Webform – zum Erstellen und Verwalten von Webformularen
• REST UI – zur Konfiguration von REST-Endpunkten und Berechtigungen
• Webform REST – das eigentliche API-Modul

---

Installation von Webform REST und Abhängigkeiten

In diesem Leitfaden werden Docker und Lando für die lokale Entwicklungsumgebung und Composer für das Abhängigkeitsmanagement verwendet.

Um das Webform REST-Modul zu installieren, führen Sie folgenden Befehl aus:

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

Um das Modul zu aktivieren:

$ lando drush en webform_rest

Aktivieren Sie zusätzlich das REST UI-Modul, um REST-Endpunkte über das Admin-Interface konfigurieren zu können:

$ lando drush en restui

Alternativ können Sie diese Module über die Admin-Oberfläche aktivieren:
/admin/modules

---

Konfiguration des Webform REST-Moduls

Sobald alle benötigten Module aktiviert sind, navigieren Sie zur REST-Konfigurationsseite:

Pfad: /admin/config/services/rest

Aktivieren Sie folgende REST-Ressourcen:

• Webform Submission
• Webform Elements
• Webform Submit

Diese Ressourcen stellen die wichtigsten Endpunkte zur Verfügung, um per REST mit Formularen und deren Daten zu interagieren.

Mindestens eine Authentifizierungsmethode muss ausgewählt sein, z.B. „Cookie“.

Um nicht authentifizierten Nutzern das Absenden von Formularen zu ermöglichen, müssen Sie die entsprechenden Berechtigungen für die Rolle Anonymous setzen. Konkret muss die Berechtigung für POST-Anfragen auf die Ressource Webform Submit gewährt werden.

Diese Berechtigung konfigurieren Sie unter:
/admin/people/permissions

Im Bereich „RESTful Web Services“ aktivieren Sie das Kästchen für „Access POST on Webform Submit resource“ bei Anonymous user. Damit können externe Nutzer oder Systeme ohne Authentifizierung Daten über die Webform REST-API auf Ihrer Drupal-Seite absenden.

Hinweis zu CORS

Wenn Sie Anfragen von einer anderen Domain als der Ihres Drupal-Systems stellen, kann es zu einem CORS-Problem kommen, wie zum Beispiel:

CORS verstehen und in Drupal 11 konfigurieren

CORS (Cross-Origin Resource Sharing) ist ein wichtiges Sicherheitskonzept, das von Browsern verwendet wird, um zu steuern, wie Ressourcen zwischen verschiedenen Ursprüngen (origin: Domain, Protokoll und Port) geteilt werden dürfen.

Vereinfacht gesagt, erlaubt CORS Servern, explizit anzugeben, welche externen Domains bestimmte Ressourcen abrufen dürfen. Ohne korrekt konfiguriertes CORS greift die Same-Origin Policy und blockiert Zugriffe von allen anderen Ursprüngen.

---

CORS in Drupal 11 konfigurieren

Drupal 11 verwaltet CORS-Einstellungen über die Datei services.yml, speziell im Abschnitt cors.config. Standardmäßig ist diese Konfiguration deaktiviert, sodass alle Anfragen von fremden Ursprüngen geblockt werden.

Um CORS für externe Clients – etwa JavaScript-Frontends oder mobile Apps – zu aktivieren, passen Sie die Einstellungen in Ihrer services.yml an. Ein Beispiel für eine großzügige Konfiguration zu Entwicklungszwecken:

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

Konfiguration von services.local.yml in der lokalen Entwicklung

In den meisten Drupal-Entwicklungsumgebungen gibt es eine Datei services.local.yml. Diese Datei überschreibt Einstellungen aus der Haupt-services.yml. Daher müssen Sie CORS-Konfigurationen auch dort entsprechend anpassen.

Stellen Sie sicher, dass Ihre CORS-Konfiguration in services.local.yml korrekt eingetragen ist, um Probleme zu vermeiden.

Cache nach der Konfiguration leeren

Nach der Anpassung der YAML-Dateien müssen Sie den Drupal-Cache leeren, damit die Änderungen greifen:

$ lando drush cr

YAML-Einrückung ist wichtig

Achten Sie bei YAML auf die korrekte Einrückung, da bereits ein einzelnes falsches Leerzeichen dazu führen kann, dass Einstellungen ignoriert werden. Wenn Ihre Änderungen nicht greifen, überprüfen Sie zuerst die Einrückungen!

---

Nutzung des Webform REST-Moduls

Nach erfolgreicher Konfiguration können Sie Formulare per REST absenden. Dazu wird eine POST-Anfrage an den Webform REST-Endpunkt mit den erforderlichen Headern und dem Payload geschickt.

Endpunkt

POST /webform_rest/submit

Erforderlicher Header

Content-Type: application/json

Beispiel: Formular-Submission mit Axios

Hier ein Beispiel für eine Anfrage mit Axios in JavaScript:

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

Dieses Beispiel zeigt, wie Sie mit Axios eine POST-Anfrage absetzen. Sie können aber auch andere HTTP-Bibliotheken oder Frameworks verwenden.

Der Request-Payload besteht hauptsächlich aus der webform_id (der technische Name des Ziel-Formulars) und den zugehörigen Feldern.

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

Die Antwort einer erfolgreichen Submission enthält folgende Felder:

• sid: Die eindeutige ID der Übermittlung
• confirmation_url: Die Bestätigungs-URL der Übermittlung
• confirmation_message: Die Bestätigungsnachricht
• confirmation_title: Der Titel der Bestätigung

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

Zusätzlich erhalten Sie auch Zugriff auf Validierungsfehler, die von Webform generiert werden. Wenn zum Beispiel ein Pflichtfeld fehlt, sieht die Antwort folgendermaßen aus:

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

Umgang mit der API-Antwort

Mit den von der API zurückgegebenen Daten können Sie Ihren Benutzer:innen programmatisch Feedback geben, zum Beispiel Erfolgsbestätigungen, Validierungsfehler oder Fehler bei der Übermittlung. Eine durchdachte Handhabung der Rückgaben verbessert das Nutzererlebnis und sorgt für Klarheit während der Interaktion.

Egal, ob Sie das Formular mit einem Frontend-Framework oder einer mobilen App verbinden – ein effektives Handling der API-Antwort ist der Schlüssel für eine reibungslose und intuitive User Experience.

---

Fazit

Das Webform REST-Modul für Drupal 11 bietet eine leistungsfähige und flexible Lösung, um per RESTful API mit Webformularen zu interagieren. Externe Anwendungen können so Formular-Daten übermitteln und manipulieren, was Drupal besonders für moderne Architekturen (z. B. Headless/Decoupled) attraktiv macht.

In diesem Artikel wurden behandelt:

• Einführung in das Webform REST-Modul
• Schrittweise Installation und Konfiguration
• Ein Praxisbeispiel zur Übermittlung von Formulardaten über die API

Obwohl sich dieser Leitfaden auf Formularübermittlung konzentriert hat, unterstützt das Webform REST-Modul auch weitere Operationen wie:

• PATCH-Requests zum Aktualisieren bestehender Übermittlungen
• GET-Requests zum Abrufen von Übermittlungen oder Auflisten von Formularfeldern
• Weitere Anpassungen bei Authentifizierung und Zugriffssteuerung

Diese fortgeschrittenen Anwendungsfälle werden in zukünftigen Anleitungen behandelt.