Hoe de Webform REST Module te gebruiken met Drupal 11: Een praktische gids

In het voortdurend evoluerende landschap van webontwikkeling onderscheidt Drupal 11 zich als een van de meest robuuste en flexibele platformen voor het bouwen van dynamische websites en applicaties. De modulaire architectuur stelt ontwikkelaars in staat om kernfunctionaliteiten aan te passen en uit te breiden om te voldoen aan een breed scala aan projectbehoeften.

Een van deze uitbreidingen is de Webform REST-module, een krachtig hulpmiddel dat naadloze integratie tussen Drupal en externe applicaties mogelijk maakt via RESTful API’s. Deze gids biedt een praktische introductie tot het gebruik van de Webform REST-module met Drupal 11, waarbij de installatie en configuratie worden doorlopen en wordt gedemonstreerd hoe je er effectief mee kunt werken.

---

Wat je zult leren

Dit artikel behandelt de volgende onderwerpen:

• Overzicht van de Webform REST-module

• Vereiste modules en afhankelijkheden

• Installeren van Webform REST en REST UI

• Configureren van de Webform REST-module

• Afhandelen van CORS

• API-verzoeken uitvoeren

• Verzoek- en antwoordpayloads begrijpen

---

Moduleoverzicht: Webform REST

De Webform REST-module breidt de mogelijkheden van Drupal’s Webform uit door formuliergerelateerde functionaliteit bloot te leggen via RESTful endpoints. Hiermee kun je handelingen uitvoeren zoals het aanmaken, bekijken, bijwerken en verwijderen van webformulieren, evenals het indienen en ophalen van formuliergegevens via HTTP-verzoeken.

Deze module is vooral nuttig voor integratie van Drupal met externe platformen zoals:

• CRM-systemen

• E-mailmarketingtools

• Mobiele applicaties

• Diensten van derden

Door deze integraties mogelijk te maken, kun je werkstromen stroomlijnen en gegevensverzameling centraliseren, wat de algehele efficiëntie van je applicatie aanzienlijk verhoogt.

---

Vereisten

Om aan de slag te gaan met Webform REST, zorg ervoor dat je de volgende modules hebt geïnstalleerd:

• Webform – voor het bouwen en beheren van webformulieren

• REST UI – voor het configureren van RESTful endpoints en permissies

• Webform REST – de hoofdmodule die de API-functionaliteit biedt

---

Installeren van Webform REST en afhankelijkheden

In deze gids gebruiken we Docker en Lando voor het beheren van de lokale ontwikkelomgeving en Composer voor dependency management.

Om de Webform REST-module te installeren, voer het volgende commando uit:

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

Om de module in te schakelen:

$ lando drush en webform_rest

Schakel daarnaast de REST UI-module in, waarmee je REST endpoints kunt configureren via de beheerinterface:

$ lando drush en restui

Je kunt deze modules ook activeren via de beheerinterface:
/admin/modules

---

Configureren van de Webform REST-module

Zodra de vereiste modules zijn ingeschakeld, navigeer naar de REST-configuratiepagina:

Pad: /admin/config/services/rest

Schakel de volgende REST-resources in:

• Webform Submission

• Webform Elements

• Webform Submit

Deze resources bieden de essentiële endpoints voor interactie met formulieren en hun gegevens via REST.

Het is noodzakelijk om ten minste één authenticatiemethode te selecteren, in ons geval "cookie".

Om niet-geauthenticeerde gebruikers in staat te stellen verzoeken in te dienen via het webformulier, moet je de juiste permissies toekennen aan de Anonieme gebruikersrol. Sta hen specifiek toe om POST-verzoeken te doen naar de Webform Submit REST-resource.

Deze permissie kan worden geconfigureerd door te navigeren naar:
/admin/people/permissions

Onder de sectie “RESTful Web Services”, vink het vakje aan voor “Access POST on Webform Submit resource” voor de Anonieme gebruiker. Dit zorgt ervoor dat externe gebruikers of systemen zonder authenticatie succesvol gegevens kunnen indienen op je Drupal-site via de Webform REST API.

Een woord over CORS

Als je van plan bent verzoeken te doen vanaf een ander domein dan waar je applicatie is geïnstalleerd, zul je waarschijnlijk een CORS-probleem tegenkomen zoals dit:

CORS begrijpen en configureren in Drupal 11

CORS (Cross-Origin Resource Sharing) is een cruciaal beveiligingsmechanisme dat door webbrowsers wordt geïmplementeerd om te bepalen hoe resources toegankelijk zijn tussen verschillende origins—waarbij een origin wordt gedefinieerd als een combinatie van domein, protocol en poort.

Eenvoudig gezegd stelt CORS servers in staat te specificeren welke externe domeinen toegang hebben tot bepaalde resources via browsergebaseerde verzoeken. Zonder correct geconfigureerd CORS-beleid vallen browsers terug op het Same-Origin Policy, dat toegang tot resources blokkeert vanuit elke andere origin dan degene die de webpagina heeft geleverd.

---

CORS configureren in Drupal 11

Drupal 11 beheert CORS-instellingen via het services.yml-bestand, specifiek onder de sectie cors.config. Standaard is deze configuratie uitgeschakeld, wat betekent dat cross-origin verzoeken worden geblokkeerd tenzij ze expliciet zijn toegestaan.

Om CORS in te schakelen voor externe clients—zoals JavaScript frontends of mobiele apps—moet je de configuratie in je services.yml-bestand aanpassen. Hier is een voorbeeld van een permissieve setup voor ontwikkel- of testdoeleinden:

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

services.local.yml configureren in lokale ontwikkeling

In de meeste Drupal lokale ontwikkelomgevingen heb je een bestand genaamd services.local.yml. Dit bestand is specifiek bedoeld om configuraties uit het hoofd-services.yml-bestand te overschrijven. Daarom kunnen wijzigingen die je in services.yml aanbrengt worden genegeerd als er tegenstrijdige of onvolledige instellingen bestaan in services.local.yml.

Om ervoor te zorgen dat je CORS-configuratie correct wordt toegepast, zorg ervoor dat je de instellingen repliceert of aanpast in services.local.yml.

Cache legen na configuratie

Na het bijwerken van je YAML-configuratiebestanden, leeg de Drupal-cache om de wijzigingen toe te passen:

$ lando drush cr

YAML-inspringing is belangrijk

Wees zorgvuldig met YAML-inspringing, omdat dit een veelvoorkomende bron van configuratieproblemen is. Zelfs een enkele verkeerd geplaatste spatie of tab kan ertoe leiden dat de instellingen worden genegeerd—wat kan leiden tot urenlang onnodig debuggen. Als je wijzigingen niet van kracht lijken te worden, controleer dan eerst je inspringing.

---

De Webform REST-module gebruiken

Zodra alles is geconfigureerd, kun je beginnen met het indienen van formulieren via REST. Het proces omvat het verzenden van een POST-verzoek naar het Webform REST-endpoint samen met de vereiste headers en payload.

Endpoint

POST /webform_rest/submit

Vereiste header

Content-Type: application/json

Voorbeeld: Een formulier indienen met Axios

Hier is een voorbeeld van een Axios-verzoek in JavaScript voor het indienen van formuliergegevens:

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

Dit voorbeeld toont hoe je een POST-verzoek kunt doen met Axios, maar je kunt ook andere HTTP-bibliotheken of frameworks gebruiken om het verzoek te versturen.

De request payload bestaat voornamelijk uit de webform_id, wat de machinenaam van het doel-formulier is, en de geregistreerde velden daarvan.

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

De response payload van een succesvolle indiening bestaat uit de volgende velden:

• sid, de unieke identificatie van de geregistreerde inzending
• confirmation_url, de bevestigings-URL van de inzending
• confirmation_message, het bevestigingsbericht
• confirmation_title, de titel van het bevestigingsbericht

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

Bovendien hebben we ook toegang tot validatieberichten die door Webform zelf worden gegenereerd. Bijvoorbeeld, als een verplicht veld niet wordt ingediend, ontvangen we de volgende response:

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

Het API-antwoord afhandelen

Met de gegevens die door de API worden teruggestuurd, kun je programmatisch feedback geven aan gebruikers—zoals succesbevestigingen, validatiefouten of mislukte inzendingen. Het aanpassen van deze responses verbetert de gebruikerservaring en zorgt voor duidelijkheid tijdens het interactieproces.

Of je nu het formulier integreert met een frontend-framework of een mobiele app, het effectief beheren van de API-response is de sleutel tot het leveren van een soepele en intuïtieve ervaring.

---

Samenvatting

De Webform REST-module voor Drupal 11 biedt een krachtige en flexibele oplossing voor interactie met webformulieren via RESTful API’s. Door externe applicaties in staat te stellen om formuliergegevens in te dienen en te manipuleren, breidt het de integratiemogelijkheden van Drupal aanzienlijk uit—waardoor het ideaal is voor moderne webarchitecturen die afhankelijk zijn van gedecouplede of headless benaderingen.

In dit artikel hebben we het volgende onderzocht:

• Een introductie tot de Webform REST-module

• Stap-voor-stap installatie en configuratie

• Hoe je gegevens via de API kunt indienen met een praktisch voorbeeld

Hoewel deze gids zich richtte op formulierindiening, ondersteunt de Webform REST-module extra handelingen die hier niet zijn behandeld, waaronder:

• PATCH-verzoeken om bestaande inzendingen bij te werken

• GET-verzoeken om inzendingsgegevens op te halen of formulier-velden te tonen

• Aanvullende aanpassingen voor authenticatie en toegangscontrole

Deze geavanceerde use-cases zullen in toekomstige tutorials worden behandeld.