Een belangrijke standaard voor het delen van de specificaties van een API is de OpenAPI Specification (OAS). Inmiddels is er een omvangrijk ecosysteem rond deze standaard en gebruiken veel partijen dit geheel of gedeeltelijk geautomatiseerd als vertrekpunt om het gebruik van een API in te richten. Ook kan men op basis van deze specificatie geautomatiseerd een testomgeving inrichten (mockserver).
OpenAPI is een internationale standaard voor het nauwkeurig en eenduidig vastleggen van REST API’s. Een OpenAPI Description (OAD) is een specifiek document om een API te beschrijven. Het beschrijft onder andere de beschikbare endpoints, de operaties, de parameters voor elke operatie, de antwoorden (responses) en andere relevante informatie over de API.
OpenAPI Specificatie (OAS) is de standaard waarin een OpenAPI Description (OAD) is opgesteld. AOS ondersteunt versie 3.1.0 van de OpenAPI Specificatie en deze zijn alleen op te stellen bij op AFD 2.0 gebaseerde AFD-definities vanwege de aansluiting op JSON Schema en het SIVI API-raamwerk. De eerste oplevering (zomer 2025) bevat nog niet de specificatie hoe om te gaan met beveiliging en de specificatie van mogelijke foutmeldingen. Dit wordt in een latere update toegevoegd evenals controles op de nalevering van afspraken die gelden voor het gebruik van het SIVI AFS API-raamwerk.
Dit zijn de belangrijkste voordelen van OpenAPI Specification 3.1:
- Open standaard die gratis te gebruiken is, en de facto geldt als de gangbare standaard voor het vastleggen en uitwisselen van API-definities.
- Uitgebreide en begrijpelijke documentatie van de API, inclusief de endpoints, parameters, request- en response-formaten, zodat het voor ontwikkelaars veel makkelijker is te begrijpen hoe de API werkt.
- Automatische codegeneratie voor zowel clients als servers in verschillende programmeertalen, dit bespaart ontwikkelaars veel tijd bij ontwikkelen en testen.
- Verbeterde interoperabiliteit door het gebruik van een gestandaardiseerde beschrijving zodat het makkelijker is om verschillende systemen met elkaar te verbinden.
Meer informatie
Op deze pagina vind je de officiële documentatie van de OpenAPI Specificatie.
Geef uw reactie op dit onderwerp.