Wat gebeurt er als een API-koppeling niet werkt?

Wat kan er misgaan met een API-koppeling?

Een API-koppeling verbindt systemen die ieder hun eigen techniek, gegevensstructuur en beschikbaarheid hebben. Daardoor kan een fout op verschillende plekken ontstaan.

Een extern systeem kan tijdelijk niet bereikbaar zijn. Een verzoek kan een time-out krijgen, aangeleverde gegevens kunnen niet voldoen aan wat het ontvangende systeem verwacht of een leverancier kan zijn API aanpassen.

Ook gedeeltelijke fouten zijn mogelijk. Stel dat een webshop honderd orders moet doorsturen en één order niet wordt verwerkt. De webshop blijft gewoon functioneren en de andere 99 orders kunnen correct aankomen. Zonder goede foutsignalering valt die ene ontbrekende order mogelijk niet direct op.

Dat maakt een stille fout soms lastiger dan een volledige storing: het proces lijkt te werken, terwijl een deel van de gegevens niet correct wordt verwerkt.

Wat gebeurt er met gegevens die niet verwerkt kunnen worden?

Dat hangt af van de API, het externe systeem, het type fout en de inrichting van de koppeling.

Bij een tijdelijke storing kan het logisch zijn om een verwerking later opnieuw te proberen. Maar dezelfde gegevens onbeperkt opnieuw versturen is geen goede oplossing. Eerst moet duidelijk zijn waarom de verwerking is mislukt en of opnieuw aanbieden veilig kan.

Er is bijvoorbeeld verschil tussen een tijdelijke en een structurele fout. Wanneer een extern systeem enkele minuten niet bereikbaar is, kan later opnieuw proberen voldoende zijn. Wordt een order afgewezen omdat een verplicht gegeven ontbreekt, dan lost opnieuw versturen niets op zolang die invoer niet wordt gecorrigeerd.

Ook moet rekening worden gehouden met de situatie waarin het ontvangende systeem een verzoek wél heeft verwerkt, maar de bevestiging daarvan niet goed terugkomt. Blind opnieuw versturen kan dan juist tot dubbele verwerking leiden.

Foutafhandeling moet daarom aansluiten op het bedrijfsproces achter de koppeling. Een gemiste productupdate heeft andere gevolgen dan een bestelling, betaling of klantaanvraag die niet correct wordt verwerkt.

Hoe merk je dat een API-koppeling niet werkt?

Een fout die zichtbaar wordt, kan worden onderzocht. Een fout die onopgemerkt blijft, kan langer gevolgen hebben voor het proces.

Bij Designpro worden errors in API-koppelingen teruggekoppeld aan de back-end developers. Zij ontvangen hiervan een melding per e-mail, zodat kan worden onderzocht wat er aan de hand is en welke actie nodig is. Ook wanneer een wijziging aan een externe API problemen veroorzaakt, kan dit zo zichtbaar worden en aanleiding geven tot een technische aanpassing.

Daarnaast wordt logging op de server opgeslagen. Wanneer er iets misgaat, kan daarin worden teruggekeken wat er rond het moment van de fout is gebeurd.

Een melding en logging hebben daarmee verschillende functies. De melding maakt duidelijk dat er iets misgaat. De logging helpt vervolgens te onderzoeken wat er is gebeurd.

Niet iedere fout kan direct worden opgelost. Ligt het probleem bij een extern systeem, dan kan de oplossing mede afhankelijk zijn van de leverancier daarvan. Signalering zorgt er wel voor dat een probleem onderzocht kan worden in plaats van ongemerkt door te blijven lopen.

Hoe voorkom je dat dezelfde actie dubbel wordt verwerkt?

Opnieuw verwerken brengt een ander risico met zich mee: dezelfde actie kan onbedoeld twee keer worden uitgevoerd.

Stel dat een webshop een order naar een extern systeem verstuurt. De webshop krijgt geen bevestiging terug en gaat ervan uit dat de verwerking is mislukt. In werkelijkheid heeft het externe systeem de order wel ontvangen. Wanneer diezelfde order opnieuw wordt aangeboden, kan dubbele verwerking ontstaan.

Daarom moet bij een API-koppeling laten maken niet alleen worden bepaald hoe gegevens worden verzonden, maar ook hoe het proces omgaat met een verwerking waarvan de status niet direct duidelijk is.

Bij Designpro kan hiervoor, afhankelijk van de koppeling en de mogelijkheden van het externe programma, met een queue worden gewerkt. Daarmee kunnen taken gecontroleerd worden aangeboden en verwerkt.

Een queue voorkomt op zichzelf niet automatisch iedere dubbele verwerking. Hoe duplicaten worden herkend en voorkomen, hangt af van de betreffende koppeling, het proces en de mogelijkheden van het externe systeem.

Juist daarom bestaat er geen universele technische oplossing die voor iedere API-koppeling hetzelfde is.

Een werkende koppeling is nog geen betrouwbare koppeling

Tijdens de ontwikkeling kan worden getest of systeem A gegevens correct naar systeem B stuurt. Daarmee is aangetoond dat de koppeling in dat scenario werkt.

In de dagelijkse praktijk ontstaan meer situaties. Wat gebeurt er wanneer een verplicht veld ontbreekt? Wat als een extern systeem langzaam reageert? Wat als veel acties kort achter elkaar plaatsvinden? En wat gebeurt er wanneer de leverancier de API verandert?

De betrouwbaarheid van een koppeling zit daarom niet alleen in succesvolle gegevensuitwisseling, maar ook in de manier waarop afwijkingen worden afgehandeld en zichtbaar worden gemaakt.

Vooraf moet bijvoorbeeld duidelijk zijn welke gegevens gecontroleerd moeten worden, welke fouten opnieuw verwerkt kunnen worden, hoe problemen worden vastgelegd, wanneer iemand moet worden gewaarschuwd en welke gevolgen een mislukte verwerking voor het vervolgproces heeft.

Hoe belangrijker de koppeling is voor de dagelijkse bedrijfsvoering, hoe belangrijker deze keuzes worden.

Wat als een externe API verandert?

Een API wordt beheerd door de leverancier van het systeem waarmee wordt gekoppeld. Die leverancier kan wijzigingen doorvoeren waar de website, webshop of het gekoppelde platform zelf geen controle over heeft.

Zo kan een manier van authenticeren wijzigen, een veld worden aangepast of een oudere versie van een API uiteindelijk niet meer worden ondersteund.

Een koppeling die bij oplevering goed functioneert, blijft daardoor niet automatisch onbeperkt hetzelfde werken.

Wanneer zo'n wijziging een fout veroorzaakt, is het belangrijk dat dit zichtbaar wordt. Foutmeldingen en logging helpen vervolgens om te achterhalen waar de gegevensuitwisseling afwijkt en welke aanpassing aan de koppeling nodig is.

Een API-koppeling blijft daarmee voor een deel afhankelijk van de systemen waarmee hij communiceert. Onderhoud stopt dus niet automatisch op het moment dat de koppeling live staat.

Praktijkvoorbeeld: meerdere systemen binnen Safetymarks

Bij Safetymarks is goed te zien hoe meerdere systemen onderdeel kunnen worden van één geautomatiseerd proces.

Designpro ontwikkelde een maatwerk webshop die is gekoppeld aan Gripp, inmiddels onderdeel van Exact. Via die koppeling worden productgegevens, webshopinformatie en verschillende administratieve processen automatisch tussen beide systemen gesynchroniseerd.

Daarnaast ontwikkelde Designpro een API-koppeling voor het verwerken van orderstatussen. Wanneer een status binnen Gripp wordt aangepast, wordt die informatie doorgegeven aan de webshop. Vanuit daar communiceren koppelingen met onder andere MyParcel de juiste verzendinformatie richting de klant.

Vereenvoudigd ontstaat daarmee een gegevensketen als:

Gripp → webshop → verzendkoppeling → klant

Hoe meer stappen automatisch op elkaar volgen, hoe belangrijker het wordt om te weten wat er gebeurt wanneer één onderdeel niet volgens verwachting functioneert. Een probleem eerder in de keten kan immers gevolgen hebben voor een processtap die daarna komt.

De openbare case beschrijft niet welke specifieke foutafhandeling voor ieder onderdeel van Safetymarks is ingericht. Dat vullen we daarom niet zelf in. De case laat wel concreet zien waarom gegevensstromen, afhankelijkheden en uitzonderingen bij gekoppelde bedrijfsprocessen vooraf moeten worden doordacht.

Bekijk de case van Safetymarks

Kun je voorkomen dat een API-koppeling ooit fouten geeft?

Nee. Je kunt de kans op problemen verkleinen en vooraf bepalen hoe fouten worden afgehandeld, maar niet garanderen dat een koppeling nooit een fout geeft.

Een externe storing, gewijzigde API of onverwachte invoer kan nooit volledig worden uitgesloten.

Het doel is daarom niet om te beloven dat er nooit iets misgaat. Belangrijker is dat vooraf wordt bepaald wat er moet gebeuren als dat wél gebeurt.

Kan een mislukte verwerking worden teruggevonden? Wordt een relevante fout zichtbaar? Kan worden vastgesteld welke gegevens wel en niet zijn verwerkt? En kan het proces daarna gecontroleerd worden hervat?

Dat bepaalt mede of een fout beheersbaar blijft of pas veel later wordt ontdekt.

Welke vragen stel je voordat je een API-koppeling laat maken?

Alleen vragen of twee systemen technisch gekoppeld kunnen worden, is niet voldoende. Minstens zo belangrijk is wat er gebeurt wanneer de normale gegevensuitwisseling wordt onderbroken.

Breng daarom vooraf in kaart:

1. Welke systemen wisselen gegevens uit?
2. Welke gegevens gaan van het ene naar het andere systeem?
3. Welk systeem is voor die gegevens leidend?
4. Welke bedrijfsprocessen zijn afhankelijk van de koppeling?
5. Wat gebeurt er wanneer gegevens niet verwerkt kunnen worden?
6. Wanneer mag een mislukte actie opnieuw worden aangeboden?
7. Hoe wordt voorkomen dat dezelfde actie onbedoeld dubbel wordt verwerkt?
8. Hoe worden fouten vastgelegd en gesignaleerd?
9. Wie moet kunnen ingrijpen wanneer verwerking stopt?
10. Hoe afhankelijk is de koppeling van wijzigingen bij externe leveranciers?

Een koppeling die één keer per dag niet-kritische informatie synchroniseert, stelt andere eisen dan een koppeling waar iedere bestelling, betaling of klantactie doorheen loopt. De technische inrichting moet aansluiten op die impact.

Wat gebeurt er dus als een API-koppeling niet werkt?

Dat moet idealiter al vóór de ontwikkeling zijn bedacht.

Een goed ingerichte koppeling houdt rekening met het feit dat externe systemen soms niet bereikbaar zijn, gegevens kunnen afwijken en API's kunnen veranderen. Welke foutafhandeling nodig is, verschilt per koppeling en bedrijfsproces.

Bij Designpro worden errors teruggekoppeld aan back-end developers en wordt logging op de server opgeslagen om problemen te kunnen onderzoeken. Waar de koppeling en het externe systeem dit toelaten, kan een queue helpen om verwerkingen gecontroleerd af te handelen.

De belangrijkste vraag is daarom niet alleen of twee systemen gegevens met elkaar kunnen uitwisselen. Minstens zo belangrijk is wat er gebeurt wanneer dat een keer niet lukt.