We kunnen wel zeggen dat een OpenAPI-specificatie (OAS) functioneert als de bron van waarheid voor je REST API's. Je bent er dan zeker van dat je API's altijd voldoen aan een bepaalde standaard. Maar wat is een OAS, wat kun je ermee en waarom is een OpenAPI-specificatie belangrijk voor een REST API? We leggen het je allemaal uit in dit blogartikel.
Wat is een OpenAPI-specificatie?
Swagger, bedenker van het concept, beschrijft een OpenAPI-specificatie (OAS) als:
“Een standaard, taalonafhankelijke interface voor RESTful API's, waarmee zowel eindgebruikers als applicaties de mogelijkheden van de service kunnen ontdekken en begrijpen, zonder toegang tot broncode of documentatie.”
Je kunt een OAS zien als een afspraak tussen de leverancier van de service en de afnemer over wat een afnemer vraagt en wat jij, als leverancier, dan levert. In de specificatie bevindt zich alle informatie die nodig is om de API aan te roepen. Bijvoorbeeld:
- Welke collecties van endpoints er zijn;
- - Wat de verwachte in- en ouput is van een endpoint;
- - Security-eisen, zoals inloggen met een gebruikersnaam en wachtwoord;
- - Welke HTTP-opties beschikbaar zijn op een endpoint, denk aan POST, PUT, GET, etc.;
- - En welke je daarvan kunt uitvoeren.
OpenAPI-specificatie is niets minder dan een contract waarin is vastgelegd wat je de afnemer van de service aanbiedt.
Worstel je met een specifiek integratievraagstuk? Of heb je een vraag over bepaalde systemen, applicaties of Integration as a Service?
Maar wat kan ik met een OpenAPI-specificatie?
De OAS is een populaire open-source tool die wordt gebruikt bij het bouwen van RESTful API's en wordt gedragen door een actieve community van ontwikkelaars. Maar wat kun je er precies mee?
1. Je API visueel maken. Het is namelijk lastig om files, waarvoor bijvoorbeeld YAML is gebruikt, met de hand te bewerken. Een OAS maakt het mogelijk om je API te bekijken.
- 2. Je API testen met testtooling, zoals Postman of Stoplight. Maar je kunt je API ook testen in een bestaande service. Of maak een mock op een bepaalde omgeving. Dan kun je alle technische aspecten van je API al uitproberen, zonder dat de service bestaat.
- 3. Code genereren in meerdere talen. Op basis van een OAS kun je een interface maken met code in meerdere programmeertalen. Zowel online als lokaal.
Waarom is een OpenAPI-specificatie belangrijk voor een REST API?
Een OAS is van belang, omdat het een contract is tussen de leverancier van de service en de afnemer. Bovendien is alles wat je ermee kunt, dus je API visueel maken, testen en code genereren in meerdere programmeertalen, essentieel om een goedwerkende REST API te ontwikkelen. Maar er zijn nog andere redenen waarom een OAS belangrijk is voor REST.
Naast dat een afnemer een OAS kan inlezen, is dit ook mogelijk in een API Gateway. Stel dat een API wordt gehost door vijf applicaties, dan zorgt een API Gateway ervoor dat die allemaal bij elkaar komen en er één uniforme API wordt getoond aan de afnemer. Verder kun je een specificatie inlezen en data mapping opzetten of throttling toepassen om het aantal aanvragen van je REST API te beheren. In verschillende fasen van de ontwikkeling van een REST API kun je OpenAPI-specificatie dus goed gebruiken.
Stel gerust al je vragen over REST API
Heb je hulp nodig bij REST? Laat dan hier je vraag achter of plan een moment in om te chatten met een van onze API-specialisten. Nu je tot het eind van dit blogartikel bent gekomen, willen we je meteen een interessante aanbieding doen: een Proof of Concept met 50% korting.
