OpenAPI-koppeling laten maken
Steeds meer systemen publiceren een OpenAPI-beschrijving: een bestand in JSON of YAML dat vastlegt welke verzoeken een API aanneemt en wat hij teruggeeft. Voor de Nederlandse overheid is de OpenAPI Specification verplicht bij het beschrijven van REST API's, en ook de API Design Rules van Logius vragen erom. Appfront bouwt koppelingen met systemen die zo'n specificatie publiceren: we lezen het contract, genereren de client, controleren elk verzoek en vangen nieuwe versies op voordat ze iets breken.
Wat is een koppeling op basis van OpenAPI?
Een koppeling op basis van OpenAPI gebruikt de gepubliceerde beschrijving van een API als contract. De OpenAPI Specification beschrijft welke gegevens een API als invoer aanneemt en als uitvoer teruggeeft, los van de programmeertaal, in een tekstbestand in YAML of JSON. Ze wordt beheerd door het OpenAPI Initiative, een open community die is opgezet door de Linux Foundation, en is inmiddels toe aan versie 3.2. Omdat de beschrijving machineleesbaar is, kunnen we er code uit genereren en elk verzoek en antwoord ertegen controleren, in plaats van de documentatie met de hand over te nemen.
Forum Standaardisatie heeft de OpenAPI Specification in 2018 op de 'pas toe of leg uit'-lijst gezet voor het beschrijven of specificeren van een REST API door overheden en de (semi-)publieke sector. Op 29 september 2026 is besloten dat de status ook voor versie 3.1 geldt, met ingang van 1 januari 2027; volgens het Forum is 3.1 niet volledig uitwisselbaar met 3.0. De REST API Design Rules van Logius, ook verplicht, schrijven voor dat de documentatie van een API een OpenAPI-beschrijving is, dat die zonder inloggen in JSON op te halen is, dat het hoofdversienummer in de URL staat en dat elke API een changelog en een uitfaseerschema publiceert.
Wij bouwen maatwerk omdat een koppeling meer is dan het aanroepen van endpoints. Welke gegevens uit uw systeem naar de API gaan, hoe u authenticeert, wat er gebeurt als de API een fout teruggeeft en hoe u omgaat met een nieuwe versie, bepaalt of de koppeling betrouwbaar is. Niet elke specificatie is volledig of klopt precies met wat de API doet. Daarom testen we het contract eerst tegen de echte API en leggen we afwijkingen vast, voordat er productiegegevens doorheen gaan.
Op het contract
De specificatie als basis.
Gecontroleerd
Elk verzoek gevalideerd.
Klaar voor versies
Wijzigingen tijdig gezien.
Hoe wij uw koppeling op basis van OpenAPI bouwen
We beginnen bij de API en uw doel: welke specificatie het systeem publiceert, welke versie van de OpenAPI Specification die volgt, hoe authenticatie werkt en welke gegevens u wilt uitwisselen met welk eigen systeem. Daarna lezen we het contract, genereren we een client en testen we die tegen een test- of acceptatieomgeving van de aanbieder, als die er is. We bouwen eerst de stroom die het meeste oplevert en laten u die met echte gegevens beoordelen. Andere endpoints volgen als dat goed loopt. Daarna bewaken we de specificatie: verschijnt er een nieuwe versie of een wijziging in de changelog, dan zien we welke onderdelen van de koppeling dat raakt.
Specificatie, versie, toegang.
Gegenereerd en getest.
De meeste waarde eerst.
Livegang, bewaking, en beheer bij nieuwe versies.
Wat een koppeling op basis van OpenAPI concreet doet
De onderdelen hieronder komen in vrijwel elke koppeling op basis van een OpenAPI-specificatie terug. Welke u nodig hebt, hangt af van de API en van uw eigen systemen.
Client
Gegenereerd uit het contract.
Validatie
Verzoek en antwoord gecontroleerd.
Versies
Wijzigingen gesignaleerd.
Mapping
Velden naar uw systeem.
Toegang
Sleutels en tokens afgeschermd.
Logboek
Elk verzoek terug te vinden.
Voor wie wij een koppeling op basis van OpenAPI bouwen
De koppeling is bedoeld voor organisaties die een eigen systeem willen laten praten met een API die met een OpenAPI-specificatie is beschreven. Hoe meer verzoeken en hoe belangrijker de gegevens, hoe meer een gecontroleerde koppeling oplevert.
Bedrijven
Koppelen met leveranciers.
Overheden
API's volgens de regels.
Ketenpartners
Gegevens tussen organisaties.
Softwarebouwers
Uw pakket aan een API.
Technologie en koppelingen
Deze pagina gaat over koppelingen met een API die een ander publiceert. Wilt u zelf een API ontwerpen en beschrijven, kijk dan naar onze pagina over een API-first platform of over de API-ontwikkelaar. Koppelt u met API's van de overheid, dan is er onze pagina over de Haal Centraal-koppeling en die over ZGW API's. Onze werkwijze leest u op software laten maken.
Waarom Appfront voor uw koppeling op basis van OpenAPI?
Een koppeling die stilletjes breekt omdat de aanbieder een veld heeft hernoemd, een verzoek dat wordt afgewezen zonder dat iemand het ziet, of documentatie die met de hand is overgenomen en niet meer klopt, kost tijd en levert verkeerde gegevens op. Daar bouwen we op: het contract als basis, controle op elk verzoek en bewaking van nieuwe versies.
Op het contract
Geen overgetypte documentatie.
Gecontroleerd
Afwijkingen direct gezien.
Bestendig
Nieuwe versies voorzien.
Security en privacy bij een koppeling op basis van OpenAPI
De koppeling gebruikt alleen de endpoints en velden die voor uw doel nodig zijn, met een eigen account of sleutel met precies de rechten die daarvoor nodig zijn. Elk verzoek wordt met tijd en resultaat vastgelegd. Gaan er persoonsgegevens door de koppeling, dan geldt de AVG en sturen en bewaren we niet meer dan nodig.
De koppeling draait in een Europees datacenter, met versleutelde verbindingen en opslag. API-sleutels, tokens en certificaten staan afgeschermd en zijn niet zichtbaar voor medewerkers. Wie in uw organisatie de gegevens uit de koppeling mag zien, stemmen we vooraf met u af.
Veelgestelde vragen over een koppeling op basis van OpenAPI
Vragen die IT-managers, architecten en productverantwoordelijken stellen voordat ze hiermee beginnen.
Een standaard om een HTTP- of REST-API te beschrijven, los van de programmeertaal. De beschrijving is een bestand in JSON of YAML dat vastlegt welke verzoeken een API aanneemt en wat hij teruggeeft. De standaard wordt beheerd door het OpenAPI Initiative, een open community die is opgezet door de Linux Foundation.
Een koppeling die de gepubliceerde beschrijving van een API als contract gebruikt. We genereren er de client uit, controleren elk verzoek en antwoord ertegen en zien aan een nieuwe versie van de specificatie welke delen van de koppeling geraakt worden.
Ja, voor het beschrijven of specificeren van een REST API staat de OpenAPI Specification sinds 2018 op de 'pas toe of leg uit'-lijst van Forum Standaardisatie. Er is besloten dat die status met ingang van 1 januari 2027 ook voor versie 3.1 geldt. Daarnaast vragen de REST API Design Rules om een OpenAPI-beschrijving.
Volgens Forum Standaardisatie is versie 3.1 niet backward compatible met 3.0: ze bevat wijzigingen die bestaande beschrijvingen en hulpmiddelen kunnen breken. Een specificatie in 3.1 kan dus onderdelen bevatten die oudere hulpmiddelen niet goed lezen. Welke versie een API gebruikt, stellen we in de eerste stap vast.
Dat komt voor. Daarom testen we het contract eerst tegen de echte API, in een testomgeving als die er is. Afwijkingen leggen we vast en melden we waar het kan bij de aanbieder, zodat de koppeling niet op een onjuiste beschrijving rust.
De koppeling bewaakt de specificatie en de changelog. Bij een wijziging zien we welke endpoints en velden geraakt worden en passen we de koppeling aan voordat de oude versie verdwijnt. Volgens de API Design Rules publiceren overheids-API's daarvoor een uitfaseerschema.
Voor organisaties die gegevens met een API uitwisselen die belangrijk zijn voor hun proces, of die met meerdere API's koppelen. Gaat het om een enkele, eenvoudige aanroep, dan volstaat soms een standaard koppeltool.
Koppelen met een API die OpenAPI gebruikt?
Vertel ons met welke API u wilt koppelen en welk systeem daarbij hoort. We laten zien hoe een koppeling op het contract daar betrouwbaar mee omgaat.