API-verzoek

Bevraagt tijdens de oproep een softwarepakket van een derde partij via zijn webinterface, slaat het antwoord op in variabelen, en neemt de uitgang Fout zodra het te lang duurt of mislukt.

In het kort

De hulptekst die in het venster wordt getoond, is: « Bevraagt een HTTP-API en extraheert JSON-waarden naar variabelen. Als de API mislukt of de timeout overschrijdt, wordt de uitgang « Fout » genomen. Gebruik {{variabele}} in de URL, de headers en de body. »

Hoe het werkt

Wat een API is

Een API is de dienstingang van een softwarepakket: een webadres dat een ander programma bevraagt, en dat niet met een te lezen pagina antwoordt, maar met gestructureerde gegevens. De meeste antwoorden zijn in JSON, een formaat dat informatie per naam ordent, zoals een formulier: {"klant": {"naam": "Janssens", "status": "premium"}}.

De module verstuurt het verzoek, leest het antwoord en extraheert daaruit wat u interesseert.

De variabelen in het verzoek

De URL, de Headers en de Body aanvaarden {{variabelen}}, die net vóór de verzending worden vervangen. Zo bevraagt men de dienst over de lopende beller: https://api.voorbeeld.com/klant/{{caller}}.

De extractie

Het antwoord moet zelden in zijn geheel worden overgenomen. De tabel onderaan koppelt een JSON-pad aan een naam van Variabele. Het pad wordt van buiten naar binnen gelezen, de niveaus gescheiden door punten: klant.naam gaat naam binnen klant zoeken. Een lijst wordt doorlopen via haar rang, beginnend bij nul: 0.naam duidt de naam van het eerste element aan.

Een leeg gelaten pad geeft het volledige antwoord terug: dit is wat nodig is wanneer de dienst rechtstreeks een getal of een woord antwoordt, zonder structuur eromheen.

Een pad dat nergens toe leidt, geeft een lege variabele, zonder fout. De uitgang OK wordt desondanks genomen, aangezien de dienst wel degelijk heeft geantwoord.

Wanneer de uitgang Fout wordt genomen

• de URL is leeg;
• de dienst antwoordt niet binnen de tijd;
• hij antwoordt met een foutcode, dat wil zeggen elke code buiten de succesfamilie;
• de stroomonderbreker is open.

De stroomonderbreker

Een dienst die uitvalt, mag niet al uw oproepen vertragen. Na 5 opeenvolgende mislukkingen naar eenzelfde server, stopt de module hem gedurende 30 seconden te bevragen: de uitgang Fout wordt onmiddellijk genomen, zonder op de tijd te wachten en zonder zelfs het verzoek te versturen. Een eerste succes zet de teller terug op nul.

Dit is een beveiliging, en het verklaart een verwarrende vaststelling: tijdens deze dertig seconden vertrekt de oproep in een oogwenk naar Fout, terwijl de dienst misschien al hersteld is.

Wat u moet invullen

De knop Een extractie toevoegen maakt een rij aan, Verwijderen verwijdert de zijne, Opslaan sluit het venster.

Stap voor stap

1. Vraag bij uw leverancier het te bevragen adres, de manier van authenticeren, en een voorbeeld van een antwoord. Zonder voorbeeldantwoord kunt u de extractiepaden niet schrijven.
2. Plaats de module API-verzoek en verbind de vorige node met haar ingang.
3. Open hem, kies de Methode en stel de Timeout in op het kortste wat uw dienst aankan.
4. Voer de URL in, door de variabelen vanuit het paneel Beschikbare variabelen in te voegen.
5. Vul de Headers in, één per regel, doorgaans de authenticatieregel die door de leverancier wordt geleverd.
6. Voor een POST of een PUT, voer de Body in.
7. Klik op Een extractie toevoegen en koppel een JSON-pad aan een naam van Variabele, zo vaak als er waarden op te halen zijn.
8. Klik op Opslaan, en verbind dan OK met het normale vervolg en Fout met een terugvalpositie die de oproep zonder het gegeven afhandelt.
9. Plaats een module Debug na de uitgang OK, met de geëxtraheerde variabelen als bericht, om te lezen wat er werkelijk werd ontvangen.
10. Klik op Opslaan, en dan op Wijzigingen toepassen in de bovenste balk.
11. Bel uw nummer, open dan het Debuglogboek van het plan en controleer de geëxtraheerde waarden.

Als het niet werkt

Alle oproepen vertrekken naar Fout terwijl de URL wel werkt in een browser. Een browser verstuurt uw sessiecookies, de module niet. Controleer de authenticatieheader. Controleer vervolgens de URL nadat de variabelen zijn vervangen: een verkeerd gespelde {{naam}} wordt leeg en levert een onvolledig adres op. Tot slot telt elk antwoord buiten de succesfamilie als een mislukking, ook een leesbare foutpagina.

De uitgang Fout wordt onmiddellijk genomen, zonder dat de dienst wordt aangeroepen. De stroomonderbreker is open: vijf opeenvolgende mislukkingen naar deze server hebben hem voor dertig seconden doen omslaan. Wacht een halve minuut voordat u concludeert, en bel dan opnieuw.

Ik heb 10 seconden gekozen en de oproep gaat na 8 verder. De wachttijd wordt bij uitvoering geplafonneerd op acht seconden, ongeacht de gekozen waarde. Dit is gewild: daarboven heeft de beller al opgehangen.

De geëxtraheerde variabele is leeg terwijl het antwoord het gegeven bevat. Het pad komt niet overeen. De niveaus worden door punten gescheiden, de lijsten worden vanaf nul geteld, en een leeg pad geeft het volledige antwoord terug. Extraheer eerst het volledige antwoord naar een variabele, lees ze in het Debuglogboek, en schrijf dan het exacte pad.

De oproep wordt verbroken wanneer de dienst niet antwoordt. De uitgang Fout is nergens mee verbonden. Verbind ze, minstens met het gebruikelijke onthaal.