Hier leggen we alles uit over (onze) API aan de hand van een aantal mooie voorbeelden: hoe je deze kunt gebruiken en waarom je er gebruik van zou moeten maken.

API staat voor Application Programming Interface. Het is de interface waarmee softwareapplicaties met elkaar kunnen communiceren. In feite kun je er iets mee aanvragen of een vraag stellen, waarna de API-aanroep de actie uitvoert die hij moet uitvoeren, nadat je hem de benodigde informatie hebt verstrekt.

Stel je voor dat je aan een tafel in een restaurant zit met een menukaart vol keuzes om uit te kiezen. De keuken is het deel van het 'systeem' dat je bestelling gaat bereiden. Wat ontbreekt, is de cruciale schakel om je bestelling door te geven aan de keuken en je eten weer aan je tafel te bezorgen. Daar komt de ober, oftewel de API, om de hoek kijken. De ober is de boodschapper – of API – die je verzoek of bestelling in ontvangst neemt en de keuken – het systeem – vertelt wat er moet gebeuren. Vervolgens brengt de ober het antwoord naar je terug; in dit geval is dat het eten.

Kortom: wanneer een bedrijf een API aan zijn klanten aanbiedt, betekent dit simpelweg dat het een reeks speciale URL’s heeft ontwikkeld die pure gegevensresponsen retourneren – wat inhoudt dat de responsen niet de presentatie-overhead bevatten die je zou verwachten in een grafische gebruikersinterface zoals een website.

We hebben vijf API-aanroepen die verschillende functies vervullen.

Een API-aanroep bestaat uit drie onderdelen:

De payload is de informatie die naar een eindpunt wordt verzonden, dat wil zeggen de gegevens die nodig zijn om een deelnemer toe te voegen.

Het eindpunt is een webadres waarnaar de informatie wordt verzonden, en het antwoord geeft aan of de API-aanroep succesvol was of niet.

Webhooks kunnen in combinatie met API-aanroepen worden gebruikt om verschillende acties te initiëren. Wanneer een webhook wordt verzonden die de vereiste payload bevat om een bepaalde API-aanroep te laten werken, voert de API-aanroep zijn taak uit en voegt de deelnemer toe. De webhooks moeten vanuit uw systeem naar ons eindpunt worden verzonden en moeten door u zelf in uw systeem worden ingesteld.

De volgende paragrafen maken deel uit van een fictief gebruiksscenario om uit te leggen hoe webhooks en API’s kunnen samenwerken.

Een HR-manager heeft een basiscursus en een examen opgezet voor nieuw aangestelde medewerkers. De HR-manager wil dat de medewerkers de cursus volgen, maar wil dat ze pas toegang krijgen tot het examen nadat ze de cursus hebben afgerond. Pas nadat ze het examen hebben gehaald, wil hij dat de medewerkers toegang krijgen tot de academie, die cursussen en examens op gemiddeld en expertniveau bevat. Hoe stelt hij dit in?

Om te begrijpen hoe dit moet worden ingesteld, hebben we al vastgesteld dat deze webhooks en API-aanroepen intern binnen het Easy LMS-systeem worden verzonden. Het proces verloopt als volgt.

De HR-manager moet een webhook aanmaken die een payload naar de examen-API verstuurt nadat de medewerker de cursus heeft afgerond. Deze webhook hoeft alleen de gegevens te bevatten die nodig zijn om de examen-API-aanroep te activeren. In dit geval gebruiken we de API-aanroep ‘Deelnemer aan examen toevoegen (uitnodigen) ’. Wanneer deze webhook is verzonden, wordt de API-aanroep geactiveerd als er een succesvol antwoord is. De API-aanroep voegt de deelnemer toe en verstuurt automatisch de uitnodiging voor het examen.

De tweede webhook die de HR-manager moet aanmaken, is voor het geval de medewerker het examen met succes aflegt om toegang te krijgen tot de academie. Ook hier geldt dat de payload van deze webhook alleen de informatie mag bevatten die de academie-API nodig heeft om de deelnemer toe te voegen en een uitnodiging te versturen. Na het verzenden van deze webhook wordt de academie-API-aanroep geactiveerd, waarna de deelnemer aan de academie wordt toegevoegd en een uitnodiging wordt verstuurd.

Samenvattend:

Een klant wil onze tool gebruiken voor het opleiden van zijn (nieuwe) medewerkers. Momenteel gebruikt hij de instelling 'Een vooraf gedefinieerde groep deelnemers' om uitnodigingsmails te versturen. Veel medewerkers beschouwen deze uitnodigingen echter als spam, en sommige van deze e-mails belanden ook in hun spamfolder. De klant wil deze uitnodigingen in plaats daarvan vanuit zijn eigen systeem versturen.

De klant maakt eerst een webhook aan die een payload verstuurt naar de Examen-API – ‘Deelnemer toevoegen zonder kennisgeving’. Wanneer een nieuwe medewerker aan uw systeem wordt toegevoegd, stuurt de webhook de payload naar de Exam API, die de medewerker toevoegt. De API-aanroep verstuurt geen uitnodiging naar deze medewerker. Wanneer de API-aanroep succesvol is, bevat het antwoord inloggegevens. Deze inloggegevens moeten vervolgens vanuit uw eigen systeem en e-mailprogramma naar de medewerker worden verzonden.

Dit werkt ook voor bestaande medewerkers; u hoeft alleen maar een webhook aan te maken die een payload naar de Exam API stuurt, waardoor de actie wordt geactiveerd om deelnemers toe te voegen zonder hen hiervan op de hoogte te stellen. De inloggegevens die in het antwoord op de API-aanroep worden teruggestuurd, kunnen vervolgens vanuit uw eigen systeem worden verzonden.

Een klant maakt examens aan in ons systeem en verkoopt deze via zijn eigen e-commercewebsite aan zijn klanten. Hij wil dit proces automatiseren nadat klanten voor een examen hebben betaald.

Om het verkoopproces te automatiseren, moeten ze een webhook gebruiken. Wanneer hun klanten een examen kopen of betalen via hun e-commercewebsite, worden ze aan hun systeem toegevoegd. De webhook die zij aanmaken, moet worden geactiveerd nadat de betaling is voltooid. Deze webhook stuurt vervolgens de relevante payload naar de examen-API-aanroep en moet een succes- of foutreactie retourneren. Bij een succesvolle reactie voegt de API-aanroep de klanten toe aan het examen waarvoor zij hebben betaald en nodigt hen uit.
​

Onze API accepteert application/x-www-form-urlencoded, multipart/form-data en JSON.

Lees meer in de volgende artikelen: