API-koppeling laten maken

Een API-koppeling is een stuk software dat twee systemen automatisch gegevens laat uitwisselen via hun programmeerinterface, de API. In plaats van een export uit het ene pakket die iemand in het andere pakket importeert, haalt de koppeling de gegevens op, zet ze om naar het formaat van het ontvangende systeem en schrijft ze weg. Dat kan op vaste momenten, of direct zodra er iets verandert.

Er zijn twee soorten opdrachten. Bij de eerste soort bestaan beide API's al, bijvoorbeeld van een boekhoudpakket en een webwinkel, en is de koppeling zelf het product. Bij de tweede soort heeft een organisatie gegevens die anderen moeten kunnen opvragen, en moet er een nieuwe API komen. Denk aan een gemeente die een eigen registratie beschikbaar wil stellen aan ketenpartners, of een bedrijf dat voorraad of planning wil delen met leveranciers.

In beide gevallen is de koppeling geen eenmalige klus. API's van leveranciers krijgen nieuwe versies, wachtwoorden en certificaten verlopen, en datavelden veranderen van betekenis. Een koppeling die niemand bewaakt, faalt meestal stil: de gegevens komen gewoon niet meer aan, en dat merkt iemand pas weken later.

Gaat het om veel bronnen die samen rapportages moeten voeden, dan is een losse koppeling per bron vaak niet de beste vorm. Kijk dan ook naar een data warehouse voor het mkb, waarin de koppelingen uitkomen op één plek.

Deze dienst past bij organisaties die een koppeling nodig hebben die meer doet dan gegevens één op één doorzetten, of die zelf een API willen aanbieden die aan overheidsstandaarden moet voldoen.

• Wel als de koppeling logica bevat, zoals ontdubbelen, omrekenen of het combineren van meerdere bronnen.
• Wel als u een API publiceert voor ketenpartners en die moet voldoen aan de NL API Design Rules.
• Wel als een koppeling persoonsgegevens verwerkt en u wilt kunnen aantonen wie wat wanneer heeft opgevraagd.
• Wel als een oud systeem eerst een API nodig heeft voordat het kan worden vervangen, zoals beschreven bij legacy-modernisering.
• Niet als beide pakketten al een kant-en-klare koppeling van de leverancier hebben die doet wat u nodig hebt. Die is goedkoper in beheer.
• Niet als het gaat om een handvol records per maand. Dan is een handmatige export vaak verstandiger dan software die onderhoud vraagt.

Twijfelt u tussen een standaardkoppeling, een integratieplatform en maatwerk, dan kan een korte toets helpen voordat u iets laat bouwen. Dat valt onder technologie- en softwareadvies.

Voor Nederlandse overheden staan vier standaarden voor API's op de lijst 'Pas toe of leg uit' van het Forum Standaardisatie. Bouwt u een API voor een gemeente, provincie of waterschap, dan zijn dit de uitgangspunten. Voor bedrijven zijn ze niet verplicht, maar wel een goed vertrekpunt.

De Design Rules leggen onder meer vast dat paden in kebab-case staan, dat het grote versienummer in de URL staat en dat het volledige versienummer in een API-Version-header terugkomt. Foutmeldingen volgen het formaat uit RFC 9457 met de velden status, title en detail. De kernregel over documentatie luidt letterlijk:

API documentation MUST be provided in the form of an OpenAPI definition document which conforms to the OpenAPI Specification (from v3 onwards).

Bron: Logius, NLGov REST API Design Rules 2.2.2, regel /core/doc-openapi, gelezen op 11 oktober 2026. Een uitgebreide uitleg per regel staat in de kennisbank onder NL API Design Rules. Gaat het om geodata, dan geldt daarnaast de geospatial-module en ligt OGC API Features voor de hand; zie WFS en OGC API Features.

U toetst een API automatisch met de linter die Logius bij de Design Rules publiceert. Het is een regelset voor het open source programma Spectral, die het OpenAPI-document controleert op de technische regels. Het voorbeeld hieronder is op 11 oktober 2026 gedraaid met Spectral 6.17.0 op een fictief OpenAPI-document voor een meldingen-API.

npm install -g @stoplight/spectral-cli
curl -L https://static.developer.overheid.nl/adr/ruleset.yaml > .linter.yaml
spectral lint -r .linter.yaml openapi.json

De eerste versie van het document had een server-URL met /v1, contactgegevens en een API-Version-header. Toch gaf de linter dit:

 10:11    error  paths-open-api-json-resource-exists  There does not exist a resource `/openapi.json` that returns the OpenAPI specification document  paths
 12:13  warning  operation-tags                       Operation must have non-empty "tags" array.                                                      paths./meldingen.get

✖ 2 problems (1 error, 1 warning, 0 infos, 0 hints)

De fout komt uit regel /core/publish-openapi. Het document moet zelf op /openapi.json onder het basispad staan. Na het toevoegen van dat pad meldde de linter een nieuwe fout, omdat dat antwoord de header access-control-allow-origin met waarde * moet hebben, zodat documentatietools het vanuit de browser kunnen lezen. Met die header en globaal gedefinieerde tags gaf de laatste run No results with a severity of 'error' found!.

Zo'n controle hoort in de bouwstraat, zodat elke wijziging aan de API automatisch wordt getoetst. De linter controleert wel alleen het document. Of de draaiende API zich er ook aan houdt, bijvoorbeeld of de header echt wordt meegestuurd, test u apart tegen de testomgeving.

Voor gemeenten is een API-koppeling vaak onderdeel van een grotere beweging. In de GEMMA-thema-architectuur voor Common Ground worden gegevens eenmalig vastgelegd en vervolgens in verschillende processen gebruikt, via gestandaardiseerde API's. Het idee is dat een applicatie gegevens opvraagt bij de bron, in plaats van een eigen kopie bij te houden die uit de pas gaat lopen. Wat dat betekent voor architectuur en inkoop, staat in de kennisbank onder Common Ground.

Voor basisregistraties zijn er de Haal Centraal-API's. Op de landingspagina van Haal Centraal staan op 11 oktober 2026 onder meer BAG Individuele Bevragingen, BRK Bevragen, BRP Personen en WOZ Bevragen als live API. Een maatwerkapplicatie die adressen of percelen nodig heeft, kan die zo bevragen in plaats van een eigen kopie te laden. Voor open gegevens zoals de BAG bestaat daarnaast de openbare route via PDOK, die op de pagina over de BAG staat beschreven.

Bevragen bij de bron heeft ook nadelen die u vooraf moet afwegen. Elke opvraging hangt af van de beschikbaarheid van de bron, en bij persoonsgegevens gelden aansluitvoorwaarden en autorisaties die per gemeente moeten worden geregeld. Een koppeling die bij een storing van de bron niets meer doet, is voor een balie-applicatie onacceptabel. Daarom kiezen we in het ontwerp per gegeven bewust tussen altijd live opvragen, kort tussenopslaan of een periodieke kopie met een vermelding van de peildatum. Die keuze staat in de documentatie, zodat een auditor kan zien waarom.

Wat dit voor gemeenten in bredere zin betekent, leest u op de sectorpagina over gemeenten.

Een koppeling krijgt toegang via een token, niet via het wachtwoord van een medewerker. OAuth 2.0 is daarvoor het gangbare raamwerk. De IETF publiceerde in januari 2025 RFC 9700 met de actuele beveiligingspraktijk voor OAuth 2.0. Daarin staat over de oude methode waarbij een applicatie de gebruikersnaam en het wachtwoord van de gebruiker zelf doorgeeft:

The resource owner password credentials grant [RFC6749] MUST NOT be used.

Bron: RFC 9700, Best Current Practice for OAuth 2.0 Security, gelezen op 11 oktober 2026. Dezelfde RFC raadt af om tokens direct in de redirect terug te geven (de implicit grant).

In de praktijk kiezen we per situatie de passende variant.

• Praten twee servers met elkaar zonder dat er een gebruiker bij is, dan past de client credentials-flow, met een sleutel per koppeling die u kunt intrekken zonder andere koppelingen te raken.
• Geeft een gebruiker een applicatie toegang tot zijn gegevens bij een andere partij, dan gebruikt u de authorization code-flow met PKCE. Voor overheden geldt dan het NL GOV Assurance profile for OAuth 2.0.
• Geheimen staan nooit in de broncode, maar in een kluis of omgevingsvariabele van de server, met een vaste vervangingsdatum.
• Elke koppeling krijgt alleen de rechten die ze nodig heeft, zodat een gelekte sleutel niet alles opent.

Waar de koppeling draait en wie de servers beheert, hoort bij de afspraken over cloud- en data-infrastructuur.

De meeste werktijd van een goede koppeling gaat naar wat er gebeurt als het misgaat. Een API kan tijdelijk onbereikbaar zijn, een verzoek kan halverwege afbreken, of de andere kant kan zeggen dat u te veel verzoeken stuurt. Dat zijn geen uitzonderingen maar het normale verloop van een week.

Idempotentie

Een verzoek dat twee keer aankomt, mag niet twee facturen of twee meldingen opleveren. De koppeling stuurt daarom een eigen kenmerk mee of controleert vooraf of het record al bestaat.

Herhalen met wachttijd

Bij een tijdelijke fout probeert de koppeling het opnieuw, met een steeds langere pauze. Bij een fout in de gegevens zelf heeft herhalen geen zin; dan gaat het record naar een wachtrij voor handmatige controle.

Begrenzing

Veel API's begrenzen het aantal verzoeken per minuut en antwoorden met statuscode 429 als u daarboven komt. De koppeling respecteert die grens in plaats van harder te proberen.

Correlatie

Elk verzoek krijgt een kenmerk dat in de logbestanden van beide kanten terugkomt, zodat een fout in een keten van systemen terug te vinden is.

Versies

Een nieuwe hoofdversie van een API die u aanbiedt, krijgt volgens de Design Rules een afbouwschema en een vaste overgangsperiode, zodat afnemers tijd hebben om over te stappen.

Bewaking betekent dat iemand een melding krijgt als er een uur geen gegevens meer binnenkomen, niet alleen als er een foutmelding is. Een stille koppeling is vaak gevaarlijker dan een die luid faalt.

Een koppeling begint bij de vraag welke gegevens waar vandaan moeten komen en wie eigenaar is van elk gegeven. De techniek komt daarna.

1. Inventarisatie. Welke systemen, welke velden, hoe vaak en in welke richting. We lezen de API-documentatie van de leveranciers en controleren met een testaccount of die klopt.
2. Gegevensafspraken. Per veld leggen we vast wat het betekent en welk systeem leidend is bij een conflict. Dat voorkomt dat twee systemen elkaar overschrijven.
3. Specificatie. Bij een nieuwe API eerst het OpenAPI-document, getoetst met de linter, zodat afnemers kunnen reageren voordat er code is.
4. Bouw en test. De koppeling draait eerst tegen testomgevingen, met geautomatiseerde tests voor de foutsituaties uit de vorige sectie.
5. Livegang met bewaking. Meldingen, een overzicht van verwerkte en geweigerde records en een korte handleiding voor wie de foutwachtrij afhandelt.
6. Beheer. Afspraken over het bijhouden van API-versies van leveranciers, het vervangen van sleutels en certificaten, en het overdragen van de code.

De broncode staat in een repository waar u toegang toe hebt, net als bij ander maatwerk software. Het werk wordt uitgevoerd door oprichter Tekin Uslu; zijn publieke code staat op GitHub, en eerder werk van de oprichter is geen referentie van TechinFlow B.V.