OpenAPI

Een begrijpelijk HTTP-API-contract vastleggen

OpenAPI is een standaard voor het beschrijven van HTTP-API’s. Een OpenAPI-beschrijving legt onder meer de aangeboden paden, bewerkingen, parameters en antwoordstructuren vast. Ze kan worden weergegeven als JSON of YAML. De beschrijvingstaal is onafhankelijk van de programmeertaal waarin de dienst is gebouwd.

Een fictief softwarebedrijf plant GET /projects/{projectId} voor zijn projectportaal. De beschrijving moet projectId als padparameter vastleggen; het succesvolle antwoord 200 moet onder meer het tekstveld name bevatten. Ook bekende foutantwoorden horen in het contract. Het pad en de velden zijn eigen ontwerpvoorbeelden, geen volledig OpenAPI-document of bestaande dienst.

Het frontendteam kan hieruit begrijpen welke informatie het moet versturen en welke antwoorden het moet verwerken. Het bestand alleen toont echter niet aan dat de draaiende implementatie dit contract volgt. Voor overdracht moeten de beschrijving en werkelijke antwoorden, inclusief fouten, worden vergeleken. Ook de betekenis van name moet worden afgesproken: een tekst met het juiste type verklaart nog niet welke naam het veld bevat.

Bronnen

• OpenAPI Initiative · OpenAPI Specification