De meeste mensen vullen formulieren in een browser in. Maar ontwikkelaars bouwen formulieren ook in eigen applicaties, mobiele apps, embedded systemen en interne tools. Die formulieren gebruiken niet de formulierbouwer met slepen en neerzetten. Ze gebruiken API's om gegevens direct naar je formulierplatform te sturen.
Dit artikel laat zien hoe formulier-API's werken, wanneer je ze nodig hebt en waar je op let bij een formulierplatform met uitgebreide API-toegang.
Wat een formulier-API is en waarom ontwikkelaars ze gebruiken
Een formulier-API is een manier waarop ontwikkelaars formuliergegevens met code versturen in plaats van via een formulier in de browser. Niemand klikt op een verzendknop van een webformulier, maar een ontwikkelaar schrijft code die gegevens direct naar het formuliersysteem stuurt.
Wanneer doe je dit?
Een eigen applicatie bouwen: Je bouwt je eigen app en wilt formuliergegevens verzamelen met je formuliertool als backend. Je code roept de formulier-API aan om te versturen.
Formulieren versturen vanuit een mobiele app: Je hebt een mobiele app met een formulier. Als gebruikers versturen, roept de code van de app de formulier-API aan.
Gegevens uit meerdere bronnen samenbrengen: Je verzamelt gegevens uit verschillende systemen en wilt alles naar één formulierplatform sturen. Je koppelcode gebruikt de formulier-API.
Bulkbewerkingen: Je hebt duizenden records die je wilt importeren. In plaats van ze met de hand in te voeren, gebruikt je code de formulier-API om ze met code te versturen.
Hoe formulier-API's werken (zonder code te hoeven begrijpen)
Een formulier-API werkt zo: je applicatie heeft gegevens. Ze wil die gegevens naar het formulierplatform sturen. Ze doet een API-aanroep (zie het als een bericht) die zegt: "hier zijn wat gegevens, sla ze alsjeblieft op." Het formulierplatform ontvangt ze, valideert ze en slaat ze op, net alsof iemand een webformulier had ingevuld en op verzenden had geklikt.
Het formulierplatform stuurt een antwoord terug dat de inzending is ontvangen en opgeslagen.
Voor het formulierplatform zijn gegevens uit een API-inzending identiek aan gegevens uit een webformulier. Beide worden gelijk behandeld.
API-authenticatie en beveiliging
Als je code een formulier-API aanroept, moet ze bewijzen dat ze bevoegd is. Dat gebeurt via authenticatie, meestal met een API-sleutel.
Een API-sleutel is als een wachtwoord voor je applicatie. Je houdt hem geheim. Wil je code gegevens versturen, dan stuurt ze de API-sleutel mee. Het formulierplatform controleert de sleutel en zegt: "ja, deze applicatie is bevoegd."
Publiceer je API-sleutel nooit in openbare code en deel hem niet. Komt iemand aan je sleutel, dan kan die formuliergegevens namens jou versturen (en dat kan een probleem zijn als je formulierinzendingen gebruikt voor zakelijk kritieke beslissingen).
Rate limiting: hoeveel API-aanroepen mogen er
De meeste formulierplatformen beperken hoeveel API-aanroepen je mag doen. Dat voorkomt misbruik en beschermt het systeem.
Een gebruikelijke limiet is "1.000 API-aanroepen per uur per API-sleutel." Doet je applicatie meer aanroepen dan de limiet, dan worden de volgende aanroepen geweigerd tot het uur voorbij is.
Controleer bij het kiezen van een formulierplatform de limieten voor API-aanroepen. Moet je 10.000 inzendingen per uur doen, dan werkt een limiet van 1.000 aanroepen per uur niet. Vraag het platform naar hogere limieten of schaalopties.
API-antwoorden en foutafhandeling
Als je code de formulier-API aanroept, krijgt ze een antwoord. Dat antwoord vertelt of de inzending is gelukt of mislukt.
Antwoord bij succes: HTTP 200 of 201. De inzending is ontvangen en opgeslagen. Je code kan doorgaan.
Antwoord bij een fout: HTTP 400, 401, 500 enzovoort. Er ging iets mis. Je code moet de fout afhandelen (opnieuw proberen, vastleggen, iemand waarschuwen).
Goede API-foutmeldingen vertellen wat er misging. "Verplicht veld ontbreekt: email" helpt. "Fout" zonder details helpt niet.
Bulkinzendingen via de API
Soms moet je meerdere inzendingen tegelijk doen. Sommige API's ondersteunen bulkbewerkingen: je stuurt 100 inzendingen in één API-aanroep in plaats van 100 losse aanroepen.
Bulkinzendingen zijn efficiënter. Ze verminderen het aantal API-aanroepen en zijn sneller klaar.
Controleer of de API van je formulierplatform bulkinzendingen ondersteunt. Moet je grote hoeveelheden gegevens importeren, dan doet deze functie ertoe.
Webhookmeldingen vanuit het perspectief van de API
Komen gegevens binnen via de API, dan wil je misschien meldingen of vervolgacties. Sommige formulierplatformen sturen webhookmeldingen voor API-inzendingen, net als voor inzendingen van webformulieren.
Dat betekent dat als je code via de API verstuurt, je systemen verderop (CRM, e-mail en meer) toch automatisch een melding krijgen.
API-documentatie en ervaring voor ontwikkelaars
Een goede formulier-API heeft uitstekende documentatie. Die legt uit hoe je authenticeert, welk endpoint je aanroept, welk gegevensformaat je gebruikt en welke fouten je kunt krijgen, en bevat codevoorbeelden.
Slechte API-documentatie maakt het leven van een ontwikkelaar zuur. Kies je een formulierplatform en heb je API-toegang nodig, lees dan eerst de API-documentatie. Is die duidelijk? Zijn er voorbeelden? Begrijp je het?
Wanneer gebruik je de API en wanneer webformulieren?
Gebruik een webformulier als: je wilt dat bezoekers een formulier in hun browser invullen. Je hebt geen code nodig. De formulierbouwer met slepen en neerzetten is genoeg.
Gebruik een API als: je een ontwikkelaar bent die een eigen applicatie bouwt. Je gegevens met code moet versturen. Je meerdere gegevensbronnen koppelt. Je de hele ervaring van het versturen wilt aanpassen.
Vaak gebruik je beide. Een website heeft webformulieren voor bezoekers. Je interne applicatie gebruikt de API om met code te versturen.
Zo ondersteunt WEMASY formulier-API's
WEMASY biedt een REST API waarmee ontwikkelaars formuliergegevens met code kunnen versturen. Authenticeer met een API-sleutel, stuur gegevens naar het endpoint en ontvang een bevestiging. API-inzendingen worden identiek behandeld aan inzendingen van webformulieren. Ze starten automatiseringen, synchroniseren met gekoppelde systemen en verschijnen in je WEMASY-dashboard. Limieten en bulkinzendingen zijn beschikbaar afhankelijk van je abonnement. Bekijk de API-documentatie in je WEMASY-account of kijk op de prijspagina voor details over API-toegang.