Werken met api's brengt frustraties met zich mee die veel developers zullen herkennen: onduidelijke documentatie, een respons die niet overeenkomt met de beschrijving in de documentatie, of de documentatie nog handmatig moeten updaten nadat nieuwe functionaliteit is toegevoegd. Ook het ontwikkelen van api’s kent de nodige uitdagingen. Veel van deze frustraties en uitdagingen kunnen worden overwonnen met de OpenAPI-specificatie.
De OpenAPI-specificatie (OAS) doet een poging om rest-api's toegankelijker te maken door ze op een gestandaardiseerde manier te beschrijven. Dit stelt mensen en computers in staat om met minimale inspanning een api te gebruiken. De OAS, die vroeger Swagger heette, heeft onlangs veel aan populariteit gewonnen. Het ecosysteem is enorm gegroeid en daardoor zijn er ontzettend veel tools op de markt gekomen die helpen om stabiele api's te ontwikkelen en te gebruiken. Dat is ook de Nederlandse overheid niet ontgaan. Zij was een early adopter en voegde de OAS al in mei 2018 toe aan haar open ict-standaarden.
Hoe werkt de OpenAPI-specificatie?
Met de OpenAPI-specificatie beschrijf je een api in een OpenAPI-document. Een OpenAPI-document kan worden geschreven in twee verschillende formaten: JSON en YAML.
Een minimaal OpenAPI-document in JSON:
{ "openapi": "3.0.0", "info": { "title": "Demo API", "version": "1.0", "description": "A sample API to describe the super powers of OpenAPI" }, "paths": {} }
Hetzelfde OpenAPI-document in YAML:
openapi: 3.0.0 info: title: Demo API version: '1.0' description: A sample API to describe the super powers of OpenAPI paths: {}
Allereerst beschrijven we de versie van de OpenAPI-specificatie die we willen gebruiken. In dit geval definiëren we versie 3.0.0. Zo kunnen we andere tools vertellen welke versie we gebruiken, zodat ze het document op de juiste manier kunnen interpreteren. Vervolgens is basale informatie uitgewerkt in het info-object. De naam van onze api, de huidige versie en een omschrijving.
Het paths-object is op dit moment nog leeg. In het paths-object kunnen operaties worden gespecificeerd. Hier wordt uiteindelijk beschreven wat de nieuwe api allemaal kan. Omdat YAML iets makkelijker leesbaar is, houden we dit formaat voor de rest van dit artikel aan. Er bestaan converters die moeiteloos documenten naar een ander formaat transformeren.