API-integraties: waarom de standaardaanpak vaak faalt

De meeste API-koppelingen draaien prima tot ze écht nodig zijn. Tijdens development lijkt alles te functioneren, in productie legt een simpele timeout of rate limit het hele systeem plat. Het verschil tussen een werkende demo en een betrouwbare integratie? Hoe je omgaat met fouten, timing en beveiliging.

Secrets horen niet in je code

Een API-sleutel hardcoded in een Python-script of een .env-bestand dat per ongeluk naar GitHub gaat: het gebeurt vaker dan je denkt. De oplossing is eenvoudig maar vereist discipline.

Gebruik een secret manager. AWS Secrets Manager, Azure Key Vault of HashiCorp Vault draaien voor een paar euro per maand en lossen drie problemen tegelijk op:

  • Je secrets liggen encrypted, niet als plaintext in een config-file
  • Je kunt sleutels roteren zonder code aan te passen
  • Elk gebruik wordt gelogd, dus je ziet wie wanneer toegang heeft gehad

Lokaal ontwikkelen mag met environment variables, maar zet voor productie een echte secrets manager op. Dat kost een middag setup en bespaart je later hoofdpijn.

HTTPS is de minimumstandaard

HTTP-verkeer is leesbaar voor iedereen tussen jouw server en de API. Dat betekent dat API-sleutels, payloads en gebruikersgegevens zichtbaar zijn. HTTPS versleutelt dit transport en voorkomt man-in-the-middle attacks.

Elke serieuze API provider ondersteunt alleen HTTPS. Gebruik je een API die nog HTTP accepteert? Rode vlag.

Waarom retry-logica het verschil maakt

Een API-aanroep kan mislukken om tientallen redenen: de server is even overbelast, het netwerk hikt, een loadbalancer wordt herstart. Als je bij elke fout meteen opgeeft, breekt je integratie bij de eerste hobbel.

Exponential backoff lost dit op. Probeer het opnieuw, maar wacht steeds langer tussen pogingen. Start met 1 seconde, dan 2, 4, 8. Dit geeft de service tijd om te herstellen zonder dat jij de boel verder overbelast.

Retry bij deze HTTP-statuscodes:

  • 500, 502, 503, 504 (serverproblemen)
  • 429 (rate limit bereikt)
  • Timeouts

Stop direct bij 400, 401, 404 of 422. Dat zijn fouten in jouw request die niet vanzelf verdwijnen.

Rate limits respecteren

APIs hebben limieten: zoveel requests per minuut of per uur. Overschrijd je die, dan krijg je een 429-statuscode terug. De Retry-After-header vertelt je hoeveel seconden je moet wachten. Lees die header en houd je eraan, anders blijf je tegen dezelfde muur aanlopen.

Staat er geen Retry-After in de response? Wacht dan een redelijke tijd voordat je het opnieuw probeert.

Circuit breakers voorkomen cascade-effecten

Stel: een externe API gaat plat. Jouw systeem blijft aanroepen sturen, elke keer een timeout, en intussen stapelen requests zich op. Uiteindelijk crasht jouw eigen applicatie onder de druk.

Een circuit breaker breekt die spiraal. Na meerdere mislukte pogingen achter elkaar stopt het systeem met aanroepen doen (open state). Na een korte periode probeert het één keer of de API weer beschikbaar is (half-open state). Lukt dat, dan gaat alles weer normaal (closed state). Lukt het niet, dan opnieuw wachten.

Dit patroon geeft een falende service de ruimte om te herstellen en beschermt je eigen systeem tegen overbelasting.

Webhooks: snel bevestigen, langzaam verwerken

Veel API’s sturen updates via webhooks: een POST-request naar jouw endpoint zodra er iets gebeurt. Het probleem: als jouw endpoint te lang bezig is, loopt de webhook-aanroep op een timeout en probeert de API het opnieuw. Dan verwerk je hetzelfde event meerdere keren.

De vuistregel: antwoord snel met een 200 OK. Doe verder niks. Geen database-updates, geen externe calls, geen e-mails versturen. Gooi het event in een queue en verwerk het asynchroon in een background job.

Idempotency: hetzelfde event meerdere keren ontvangen

APIs kunnen hetzelfde webhook event meerdere keren sturen, bijvoorbeeld omdat ze na een korte tijd nog geen bevestiging hadden. Zonder bescherming verwerk je dezelfde order, betaling of notificatie dubbel.

Los dit op met event-IDs: sla bij elk event de ID op in je database en check voor verwerking of je ‘m al eerder hebt gezien. Zo niet, verwerk. Zo wel, negeer.

Webhook-beveiliging in drie stappen

Iedereen kan een POST-request naar jouw webhook-endpoint sturen. Zonder verificatie kun je niet weten of het echt van de API komt of van iemand die zich voordoet als de API.

Drie stappen:

  1. Verifieer de HMAC-signature. De meeste APIs ondertekenen elke webhook met een hash van de payload. Bereken zelf die hash en vergelijk. Komen ze niet overeen, reject de request.
  2. Gebruik alleen HTTPS-endpoints. Geen HTTP, ook niet voor test-webhooks.
  3. Negeer oude events. Een event dat te oud is, is verdacht. Dit voorkomt replay attacks.

Gebruik voor signature-vergelijking crypto.timingSafeEqual of een vergelijkbare functie. Een gewone string-vergelijking lekt timing-informatie en maakt timing attacks mogelijk.

Testen zonder productiedata

Test nooit tegen een productie-API. Je riskeert echte transacties, verzonden e-mails of aangepaste data. Elke serieuze API heeft een sandbox-omgeving met dummy-gegevens en test-keys (vaak herkenbaar aan een test_-prefix).

Automatiseer je tests en draai ze in je CI/CD-pipeline. Test niet alleen de happy path. Simuleer ook timeouts, malformed responses, rate limits en gedeeltelijke data.

Mock externe API-calls in unit tests. Dit maakt je tests snel, betrouwbaar en onafhankelijk van de beschikbaarheid van de API. Integratie-tests tegen de sandbox draaien apart.

Logging: genoeg detail, geen secrets

Goede logs laten je zien wat er misging zonder dat je het hele systeem opnieuw hoeft op te bouwen. Log bij elke API-call:

  • HTTP-methode, URL en headers (zonder auth-tokens)
  • Request en response body
  • Statuscode, response time en eventuele errors
  • Context: user-ID, request-ID, correlation-ID voor tracing

Log nooit API-sleutels, wachtwoorden, creditcardnummers, e-mailadressen of andere persoonsgegevens. Redact die velden voor je logt.

Hoe lang duurt een solide integratie?

Een werkende proof-of-concept bouw je in een paar uur. Een productie-integratie met error handling, retry-logica, monitoring en beveiliging kost meerdere dagen. Reken voldoende tijd voor testen en het opzetten van logging en alerting.

Streef naar hoge uptime. Zonder retry-logica en circuit breakers is dat moeilijk te bereiken.

Waar begin je deze week?

Kies één punt en pak het aan. Haal API-sleutels uit je code en zet ze in environment variables (lokaal) of een secret manager (productie). Voeg exponential backoff toe aan je API-calls, dat voorkomt dat een tijdelijke storing je hele workflow platgooit. Test je webhook-endpoint: antwoordt het snel en verifieer je de signature?

API-integraties lijken eenvoudig tot ze productieverkeer krijgen. Bouw van tevoren voor de dingen die misgaan, niet achteraf als ze al mis zijn gegaan.


AI Generated