Koppelen via een API: wat je vastlegt vóór de bouw
Een API maakt koppelen mogelijk, maar niet vanzelf betrouwbaar. Welke afspraken over sleutels, limieten, fouten en versies je vastlegt voordat er gebouwd wordt.
Niyazi Gökmen, Lead security · · 5 min
Een API is de beste route om twee systemen met elkaar te laten praten. Hij is gedocumenteerd, geeft gestructureerde gegevens terug, en de leverancier heeft hem bedoeld om gebruikt te worden. In het artikel over koppelen zonder API staat hij daarom bovenaan. Maar een API die bestaat, is nog geen koppeling die werkt. Wat een koppeling betrouwbaar maakt, zit in afspraken die je vóór de bouw vastlegt en die in een offerte meestal ontbreken.
Wij leggen er altijd zes vast: wiens sleutel het is, hoe wijzigingen binnenkomen, wat er bij drukte gebeurt, wat er bij een fout gebeurt, wat er bij een nieuwe versie gebeurt, en wat het contract erover zegt.
Wiens sleutel is het?
Een koppeling logt in met een API-sleutel of via OAuth, namens iemand. Te vaak is dat de medewerker die de koppeling ooit heeft aangezet. Gaat die persoon weg en wordt het account opgeheven, dan stopt de koppeling, en tot die tijd staat in elk logboek een mens waar een systeem handelde. Maak een apart serviceaccount of een aparte app-registratie op naam van de organisatie, met alleen de rechten die de koppeling nodig heeft.
Leg ook vast waar de sleutel staat en wie hem kan inzien. Een sleutel in een configuratiebestand, een gedeelde notitie of een mail aan de bouwer is een sleutel die je niet meer kunt terughalen. Hij hoort in een kluis, met een vervaldatum en een procedure om hem te vervangen zonder dat de koppeling stilvalt.
Ophalen of laten melden
Een koppeling kan op twee manieren weten dat er iets is veranderd. Hij vraagt periodiek of er iets nieuws is, of het bronsysteem meldt het zelf met een webhook zodra er een order, een status of een urenstaat bij komt. Een webhook is sneller en zuiniger, maar een melding die niet aankomt, wordt niet altijd opnieuw verstuurd. Wij bouwen daarom meestal allebei: de webhook voor snelheid, en een periodieke controle die vangt wat de webhook mist.
Limieten en dubbele berichten
Elke API heeft aanroeplimieten: zoveel verzoeken per minuut, per uur of per dag. Bij normaal gebruik merk je daar niets van. Bij de eerste grote import, bij de maandafsluiting of na een storing, als alles tegelijk wordt ingehaald, loop je ertegenaan. Vraag de limieten op, reken ze door tegen je piek in plaats van je gemiddelde, en bouw de koppeling zo dat hij bij een limiet wacht en opnieuw probeert in plaats van gegevens te laten vallen.
Opnieuw proberen heeft een keerzijde. Is een order wel aangekomen maar het antwoord niet, dan maakt de tweede poging een tweede order. Geef daarom elk bericht een eigen kenmerk en laat het ontvangende systeem een bekend kenmerk herkennen. Veel API's ondersteunen dat met een zogenoemde idempotentiesleutel; waar dat niet kan, controleer je vóór het aanmaken of het record al bestaat.
Als het misgaat
- Een tijdelijke fout, zoals een time-out of een limiet, probeert de koppeling zelf opnieuw, met steeds langere tussenpozen.
- Een blijvende fout, zoals een ontbrekend verplicht veld of een onbekende klant, gaat naar een wachtrij die een mens ziet, met het originele bericht erbij.
- Een koppeling die een tijd niets verwerkt terwijl dat wel verwacht werd, geeft een alarm. Stilte is de fout die het langst onopgemerkt blijft.
- Elke fout is terug te vinden bij het record waar hij over gaat. Een technisch logbestand alleen is niet genoeg.
Versies en uitfasering
Leveranciers vernieuwen hun API. Een veld krijgt een andere naam, een eindpunt verdwijnt, een oude versie wordt uitgezet. Goede leveranciers kondigen dat ruim vooraf aan, maar die aankondiging gaat naar het mailadres dat bij de registratie is opgegeven. Leg vast welke versie de koppeling gebruikt, wie de aankondigingen ontvangt en wie beoordeelt wat ze betekenen. Vraag vóór de bouw naar het versiebeleid: hoe lang wordt een versie ondersteund, en hoe ver vooraf hoor je dat hij stopt?
Het contract naast de techniek
Een API is ook een commerciële afspraak. Leveranciers zetten toegang soms achter een duurder abonnement, rekenen per aanroep, of beperken wat je met de gegevens mag doen. Vraag schriftelijk wat de toegang kost, of dat mag veranderen en met welke opzegtermijn, en of je bij een overstap je gegevens in een bruikbaar formaat meekrijgt. Een koppeling die je na twee jaar niet meer kunt betalen, is geen besparing geweest.
Wat we afraden: een koppeling laten bouwen waar na de oplevering niemand eigenaar van is. Een API verandert, een sleutel verloopt, een limiet wordt verlaagd, en zonder eigenaar merkt de eerste medewerker die een order mist het als eerste. Bouw ook geen synchronisatie in twee richtingen als één richting volstaat: twee systemen die elkaar bijwerken, maken bij een fout twee waarheden in plaats van één.
Wat je nu kunt doen: pak één bestaande koppeling en beantwoord de zes vragen uit dit artikel. Op wiens account draait hij, hoe hoort hij van wijzigingen, wat zijn de limieten, wat gebeurt er bij een fout, welke versie gebruikt hij, en wat staat er in het contract? Waar jij het antwoord niet weet, weet waarschijnlijk niemand het. Tel ook hoe vaak die koppeling het afgelopen kwartaal met de hand is hersteld; dat is het getal waaraan je na de verbetering meet.