API’s spelen een cruciale rol in de huidige verbonden wereld. Bijna elke app op je mobiele apparaat wordt ondersteund door een API. Om deze reden is API-ontwikkeling tegenwoordig een trending onderwerp. Er zijn veel standaarden die populair zijn geworden in de API-ontwikkelingsruimte. Een van die standaarden is het formaat van API-specificatiedocumenten. OpenAPI Specificatie (voorheen bekend als Swagger) is de de facto standaard geworden voor het beschrijven van API’s in de moderne API-wereld. Er zijn ook veel geweldige tools rond gebouwd om API-ontwikkeling en API lifecycle management te vergemakkelijken. In dit artikel bespreken we het belang van de OpenAPI specificatie en 3 geweldige OpenAPI tools die je API-ontwikkelingsproces productiever en efficiĂ«nter kunnen maken.
Het meest uitdagende aspect van API Ontwikkeling
Er zijn 2 belangrijke partijen in het API-ecosysteem: de API-uitgevers en de API-gebruikers. De API-uitgever stelt een API beschikbaar en de API-gebruiker gebruikt deze. De API zelf is echter niet het enige wat de API-uitgever aan de API-gebruiker levert. Er zijn ook andere gerelateerde producten zoals API-documentatie, SDK’s, Postman Collecties, enzovoort. Elke keer dat er iets verandert in de API, moet de API-uitgever al deze gerelateerde producten ook bijwerken. Dit kan erg moeilijk zijn om handmatig bij te houden en dienovereenkomstig bij te werken. Bovendien, als je veel API’s bezit, is het handmatig bijwerken van al deze producten wellicht niet schaalbaar. Wat als je een manier had om dit proces te automatiseren? Wat als elke keer dat je je API wijzigt, alle genoemde downstream producten automatisch worden bijgewerkt? Klinkt geweldig, toch? Het is eigenlijk mogelijk. Alles wat je nodig hebt is een bron van waarheid voor je API. Hier komen OpenAPI-bestanden (of OAS-definities) in actie.
Hoe OpenAPI-bestanden de dag kunnen redden
Wat betekent het dat OpenAPI-bestanden de bron van waarheid van je API kunnen zijn? Dat is eenvoudig. Je begint je API gewoon met een OpenAPI-bestand. Dit wordt “API-first ontwikkeling” genoemd. Zodra je OpenAPI-bestand klaar is, genereer je alles wat je nodig hebt vanuit dit bestand. Er zijn veel tools beschikbaar die API-documentatie, SDK’s, Postman Collecties, enzovoort kunnen genereren vanuit OpenAPI-bestanden. Maar wat betreft de daadwerkelijke implementatie? Het goede nieuws is dat je zelfs gedeeltelijk de API-implementatie kunt genereren. Wat je genereert is in feite het skelet van je API-implementatie. Als je een Java-ontwikkelaar bent, genereer je bijvoorbeeld een paar Java-interfaces en een set modelklassen. Vervolgens hoef je alleen maar die interfaces te implementeren. Dit betekent dat je codebase uit twee soorten code bestaat: gegenereerde code en handmatig geschreven code. Wat betreft de wijzigingen? Als je een wijziging wilt aanbrengen in je API-contract, doe je dit in het OpenAPI-bestand en genereer je je code opnieuw. Het vervangt de gegenereerde code maar raakt je handmatig geschreven code niet aan. Je moet mogelijk enkele delen van de handmatig geschreven code bijwerken om overeen te komen met de nieuw gegenereerde wijzigingen. Dat is het. Zo werkt de API-first benadering.
OpenAPI tools om je leven gemakkelijker te maken
Er zijn veel geweldige tools die verschillende aspecten van OpenAPI-bestanden dekken. Dit omvat tools die code genereren, documentatie genereren, SDK’s genereren, tests genereren, enzovoort. Dergelijke tools zijn meestal erg populair omdat ze zeer gebruikelijke use-cases dekken. Je kunt dus gemakkelijk veel informatie over dergelijke tools op internet vinden. Daarom gaan we het niet hebben over die tools die de meest gebruikelijke use-cases dekken. In plaats daarvan bespreken we 3 geweldige OpenAPI tools die niet zo populair zijn, maar essentieel kunnen zijn voor de API-ontwikkelingslevenscyclus.
Spectral: OpenAPI Linter Tool
We bespraken hoe de API-first benadering het leven gemakkelijker maakt voor API-ontwikkelaars. Het definiëren en bijwerken van OpenAPI-bestanden kan echter erg moeilijk zijn vanwege mogelijke syntactische en semantische fouten, tenzij we een goed validatiemechanisme hebben dat elk OpenAPI-bestand dat we schrijven en bijwerken kan valideren. Hier komt de Spectral linter tool goed van pas.
Spectral is een open-source linter tool voor OpenAPI-bestanden. Het heeft een set ingebouwde regels om de geldigheid van OpenAPI-bestanden te waarborgen. Deze standaardregelset vertegenwoordigt de OpenAPI Specificatie (OAS) die definieert wat een OpenAPI-bestand is, hoe het eruit moet zien, wat het kan doen, hoe het kan worden uitgebreid, enzovoort. Daarnaast kun je ook je eigen aangepaste Spectral-regels definiëren om extra regels te valideren die je wilt afdwingen, bijvoorbeeld de interne REST API ontwerprichtlijnen van je bedrijf.
Hier zijn enkele standaardregels die erg nuttig zijn in de dagelijkse API-ontwikkeling:
- API-eindpunten mogen niet dubbelzinnig zijn, wat betekent dat er geen overlappende API-eindpunten mogen zijn.
- OpenAPI-bestanden moeten “Servers” gedefinieerd hebben.
- API-verzoek- en respons-payload voorbeelden in een OpenAPI-bestand moeten geldig zijn volgens de API-modellen die in het OpenAPI-bestand zelf zijn gedefinieerd.
- Gegeven voorbeelden moeten gekoppeld zijn aan ten minste Ă©Ă©n van de API-eindpunten.
Zoals eerder vermeld, kun je naast de standaardregels ook je eigen aangepaste regels definiĂ«ren. Bijvoorbeeld, er kunnen organisatie-specifieke API-richtlijnen zijn die je wilt afdwingen op de API’s van je organisatie. De volgende zijn enkele voorbeelden:
- Padparameters, queryparameters, enzovoort moeten in camel-case zijn.
- Elk verzoek- en responsmodel moet voorbeelden hebben.
- Elk API-eindpunt moet een of meer beveiligingsschema’s toegewezen hebben.
- Enum-waarden mogen niet gedupliceerd zijn.
Hier is hoe je een aangepaste Spectral-regel kunt definiĂ«ren. Deze aangepaste regel zegt dat API’s altijd een beschrijving moeten hebben gedefinieerd in hun info-object.
rules:
info-description:
given: $.info
then:
field: description
function: truthy
Naast het definiĂ«ren van je eigen regels, kun je ook de standaardregels aanpassen. Een manier om dit te doen is door de ernst van de standaardregels te wijzigen. Je kunt bijvoorbeeld een standaard “fout”-niveau regel wijzigen in een “waarschuwing”. Of je kunt de standaardregels zelfs volledig uitschakelen.
Spectral stelt je in staat een hiërarchie van regelbestanden te definiëren waarbij het ene regelbestand door een ander kan worden overschreven. In dit artikel gaan we dat niet in detail bespreken. Er komt binnenkort een apart artikel over Spectral alleen dat diep ingaat op zijn functies.
Hier zijn enkele belangrijke links naar Spectral:
Spectral ondersteunt OpenAPI Specificatie v2.0, v3.0 en v3.1 versies.
Als je een gebruiker bent van WSO2 API Manager, is er goed nieuws voor je. WSO2 API Manager ondersteunt nu Spectral standaard vanaf APIM 4.2.0.
OpenAPI Diff Tool
OpenAPI diff tool is een andere geweldige open-source OpenAPI tool. Het laat je het verschil zien tussen 2 API’s. Dit is vooral belangrijk wanneer je het verschil wilt zien tussen 2 versies (of revisies) van dezelfde API.
OpenAPI diff tool is beschikbaar als een CLI evenals een Java-bibliotheek. Wanneer je de tool uitvoert, hoef je alleen maar de twee OpenAPI-bestanden die je wilt vergelijken als invoer te geven, en dan geeft het je de verschillen in een mooi formaat. Je kunt ook het uitvoerformaat kiezen. Het ondersteunt HTML, Json en Markdown (.md).
Hier is een voorbeeld van hoe je de CLI kunt gebruiken om het verschil tussen newsapi_v5.yaml en newsapi_v6.yaml bestanden te genereren en het resultaat in een bestand genaamd newsapi_diff_v5_v6.md in markdown-formaat te schrijven.
openapi-diff /specs/newsapi_v5.yaml /specs/newsapi_v6.yaml --markdown /output/newsapi_diff_v5_v6.mdDe uitvoer bevat voornamelijk de volgende secties:
- Nieuwe eindpunten
- Verwijderde eindpunten
- Verouderde eindpunten
- Gewijzigde eindpunten
- Gewijzigde extensies
- Gewijzigde elementen
- Brekende (niet achterwaarts-compatibele) wijzigingen
- Niet-brekende (achterwaarts-compatibele) wijzigingen
Laten we nu enkele praktische use-cases van de diff tool bespreken.
Als API-ontwikkelaar, wanneer je op het punt staat een nieuwe versie van je API uit te brengen, moet je mogelijk ook release-opmerkingen voorbereiden. En je moet misschien zelfs een “wat is er nieuw” pagina voorbereiden. In die documenten moet je API-contractwijzigingen en functionele wijzigingen van de API opnemen. De OpenAPI diff tool kan zeer nuttig zijn bij het genereren van alle contractwijzigingen die je hebt in de nieuwe API-versie.
Een andere belangrijke use-case van de OpenAPI diff tool is zijn vermogen om brekende wijzigingen te detecteren. Wanneer je kleine versies van je API uitbrengt, moet je ervoor zorgen dat ze geen brekende (niet achterwaarts-compatibele) wijzigingen introduceren. Anders kan het je klantintegraties/applicaties breken, wat je ten koste van alles moet vermijden. Het hebben van een tool in het API-ontwikkelingsproces voor het vroegtijdig detecteren van brekende API-wijzigingen kan je leven gemakkelijker maken. De OpenAPI diff tool is slim genoeg om te herkennen of een gedetecteerde wijziging een brekende wijziging is of niet. De CLI tool heeft de ingebouwde optie “–fail-on-incompatible” voor dit doel.
Hoewel de CLI tool erg eenvoudig te gebruiken is, kun je met de Java-bibliotheek van de tool nog meer aangepaste dingen doen door zijn mogelijkheden uit te breiden. Of je de CLI tool of de Java-bibliotheek moet gebruiken, hangt af van of je eenvoud en flexibiliteit wilt.
Hier zijn enkele belangrijke links naar de OpenAPI diff tool:
Volgens de officiële documentatie ondersteunt de OpenAPI diff tool alleen de OpenAPI Specificatie v3.0 versie. Echter, volgens enkele discussies in de git repo, ondersteunt het mogelijk ook de OpenAPI v3.1 versie in zijn huidige staat, hoewel dit niet direct wordt vermeld in de officiële documentatie.
OpenAPI Merge Tool
Dit is een andere geweldige OpenAPI tool die je de mogelijkheid geeft om meerdere OpenAPI-bestanden samen te voegen tot Ă©Ă©n. Deze tool is nuttig wanneer meerdere teams gerelateerde API’s ontwikkelen (bijv. microservices), en je ze collectief aan gebruikers wilt aanbieden.
De taak van de OpenAPI Merge tool is heel eenvoudig. Het vereist 2 of meer OpenAPI-bestanden als invoer en het voegt ze eenvoudig samen en geeft ze uit als een enkel OpenAPI-bestand. Echter, in tegenstelling tot de vorige 2 tools die we bespraken, vereist de OpenAPI Merge tool een configuratiebestand waarin de paden naar invoer- en uitvoerbestanden worden gedefinieerd. Hier is een voorbeeld van een configuratiebestand.
Soms kan het samenvoegen van OpenAPI-bestanden gecompliceerd zijn omdat de gegeven invoerbestanden dezelfde of soortgelijke resources en modellen kunnen hebben. Het samenvoegen van dergelijke bestanden kan merge-conflicten veroorzaken. De OpenAPI Merge tool behandelt dergelijke conflicten op 2 manieren:
- Als beide OpenAPI-bestanden hetzelfde modelschema hebben, worden ze als hetzelfde behandeld en wordt er slechts Ă©Ă©n van gekopieerd naar het uitvoerbestand. Dit wordt dan verwezen door de andere componenten die uit beide invoerbestanden zijn gekopieerd.
- Als de schemanaam hetzelfde is maar hun eigenschappen verschillen in 2 invoerbestanden, kunnen ze niet als hetzelfde model worden behandeld. In dat geval moeten beide modellen naar het uitvoerbestand gaan, maar ze kunnen niet dezelfde naam hebben. Dit vereist het hernoemen van een van de conflicterende modelschema’s. In dergelijke gevallen vereist de tool hulp van een domeinexpert zoals de API-ontwikkelaar om te beslissen welk OpenAPI-bestand prioriteit moet krijgen. Dus de tool verwacht dat de ontwikkelaar de tool vertelt welke modellen van welke invoer-OpenAPI-bestanden moeten worden hernoemd in een conflict en hoe ze moeten worden hernoemd. Het goede nieuws is dat dit vooraf kan worden geconfigureerd in het configuratiebestand van de tool. Je kunt configureren welke componenten van welke invoer-OpenAPI-bestanden moeten worden hernoemd en met welk voorvoegsel of achtervoegsel. Hieronder staat een voorbeeldconfiguratie.
Dat is slechts Ă©Ă©n belangrijke functie van deze tool. Hieronder staan enkele andere belangrijke functies.
- Voorvoegsels en achtervoegsels kunnen worden toegevoegd aan gegeven OpenAPI-bestanden, ongeacht conflicten.
- Eindpunten kunnen worden geselecteerd of verwijderd op basis van hun tags.
- Padwijzigingen kunnen worden gedaan door delen te strippen en toe te voegen.
- OpenAPI-bestandsinfo-beschrijvingen kunnen samen worden gevoegd, of een volledig nieuwe beschrijving kan worden ingesteld in het samengevoegde uitvoerbestand.
Hier zijn enkele belangrijke links naar de OpenAPI Merge tool:
Momenteel ondersteunt de OpenAPI Merge tool alleen de OpenAPI Specificatie v3.0 versie. Ondersteuning voor OpenAPI v3.1 moet nog komen.
Conclusie
In dit artikel hebben we besproken hoe belangrijk OpenAPI-bestanden zijn voor de API-ontwikkelingslevenscyclus en hoe OpenAPI tools een betere en gemakkelijkere omgang met OpenAPI-bestanden faciliteren. Het belangrijkste is dat er 3 geweldige OpenAPI tools werden geĂŻntroduceerd in dit artikel: de Spectral linter tool, de OpenAPI diff tool en de OpenAPI merge tool. We hebben besproken welke problemen elk van deze tools oplost, hoe ze te gebruiken zijn en wat hun belangrijkste functies zijn. Dus, als je een API-ontwikkelaar, een productmanager of iemand die werkt in API-ontwikkeling bent, kan dit artikel een waardevolle bron zijn. Ga nu verder en probeer deze uitstekende tools uit: het zal zich lonen op de lange termijn van je API-reis.
