DevOps en CI/CD gebruiken om API's te publiceren

Met de strategische waarde van API's in de onderneming is het gebruik van DevOps-technieken voor continue integratie (CI) en implementatie (CD) een belangrijk aspect van API-ontwikkeling geworden. In dit artikel worden de beslissingen besproken die u moet nemen om DevOps-principes te gebruiken voor het beheer van API's.

API DevOps bestaat uit drie onderdelen:

Diagram met de API DevOps-stroom.

Elk onderdeel van de API DevOps-pijplijn wordt hieronder besproken.

API-definitie

Een API-ontwikkelaar schrijft een API-definitie door een specificatie, instellingen (zoals logboekregistratie, diagnostische gegevens en back-endinstellingen) en beleidsregels op te geven die moeten worden toegepast op de API. De API-definitie biedt de informatie die nodig is om de API in te richten op een Azure API Management-service. De specificatie kan zijn gebaseerd op een OP standaarden gebaseerde API-specificatie (zoals WSDL, OpenAPI of GraphQL), of kan worden gedefinieerd met behulp van de ARM-API's (Azure Resource Manager) (bijvoorbeeld een ARM-sjabloon waarin de API en bewerkingen worden beschreven). De API-definitie verandert na verloop van tijd en moet worden beschouwd als 'broncode'. Zorg ervoor dat de API-definitie wordt opgeslagen onder broncodebeheer en de juiste beoordeling heeft voordat de implementatie wordt uitgevoerd.

Er zijn verschillende hulpprogramma's voor het produceren van de API-definitie:

  • De Azure APIOps Toolkit biedt een werkstroom die is gebouwd op een Git-broncodebeheersysteem (zoals GitHub of Azure-opslagplaatsen). Er wordt een extractor gebruikt om een API-definitie te produceren die vervolgens door een uitgever wordt toegepast op een doel-API Management-service. APIOps ondersteunt op dit moment REST- en GraphQL-API's.
  • Het hulpprogramma dotnet-apim converteert een goed gevormde YAML-definitie naar een ARM-sjabloon voor latere implementatie. Het hulpprogramma is gericht op REST API's.
  • Terraform is een alternatief voor Azure Resource Manager om resources in Azure te configureren. U kunt een Terraform-configuratie maken (samen met beleid) om de API op dezelfde manier te implementeren als een ARM-sjabloon.

U kunt ook op IDE gebaseerde hulpprogramma's voor editors zoals Visual Studio Code gebruiken om de artefacten te produceren die nodig zijn om de API te definiëren. Er zijn bijvoorbeeld meer dan 30 invoegtoepassingen voor het bewerken van OpenAPI-specificatiebestanden op de Visual Studio Code Marketplace. U kunt ook codegeneratoren gebruiken om de artefacten te maken. Met de CADL-taal kunt u eenvoudig bouwstenen op hoog niveau maken en deze vervolgens compileren in een standaard-API-definitie-indeling, zoals OpenAPI.

API-goedkeuring

Zodra de API-definitie is geproduceerd, verzendt de ontwikkelaar de API-definitie ter beoordeling en goedkeuring. Als u een op Git gebaseerd broncodebeheersysteem gebruikt (zoals GitHub of Azure-opslagplaatsen), kan de verzending worden uitgevoerd via een pull-aanvraag. Een pull-aanvraag informeert anderen over wijzigingen die zijn voorgesteld aan de API-definitie. Zodra de goedkeuringspoorten zijn bevestigd, voegt een fiatteur de pull-aanvraag samen in de hoofdopslagplaats om aan te geven dat de API-definitie kan worden geïmplementeerd in productie. Het pull-aanvraagproces stelt de ontwikkelaar in staat om eventuele problemen op te lossen die tijdens het goedkeuringsproces zijn gevonden.

Zowel GitHub als Azure-opslagplaatsen maken het mogelijk om goedkeuringspijplijnen te configureren die worden uitgevoerd wanneer een pull-aanvraag wordt ingediend. U kunt de goedkeuringspijplijnen configureren voor het uitvoeren van hulpprogramma's zoals:

Notitie

Azure-API's moeten voldoen aan een strikte set richtlijnen die u kunt gebruiken als uitgangspunt voor uw eigen API-richtlijnen. Er is een Spectral-configuratie voor het afdwingen van de richtlijnen.

Zodra de geautomatiseerde hulpprogramma's zijn uitgevoerd, wordt de API-definitie gecontroleerd door het menselijk oog. Hulpprogramma's ondervangen niet alle problemen. Een menselijke revisor zorgt ervoor dat de API-definitie voldoet aan de organisatiecriteria voor API's, waaronder naleving van richtlijnen voor beveiliging, privacy en consistentie.

API-publicatie

De API-definitie wordt gepubliceerd naar een API Management-service via een release-pijplijn. De hulpprogramma's die worden gebruikt om de API-definitie te publiceren, zijn afhankelijk van het hulpprogramma dat wordt gebruikt om de API-definitie te produceren:

Kan ik andere broncodebeheer- en CI/CD-systemen gebruiken?

Ja. Het beschreven proces werkt met elk broncodebeheersysteem (hoewel APIOps vereist dat het broncodebeheersysteem op Git is gebaseerd). Op dezelfde manier kunt u elk CI/CD-platform gebruiken, zolang het kan worden geactiveerd door een check-in en opdrachtregelprogramma's kunnen uitvoeren die met Azure communiceren.

Aanbevolen procedures

Er is geen industriestandaard voor het instellen van een DevOps-pijplijn voor het publiceren van API's en geen van de genoemde hulpprogramma's werkt in alle situaties. We zien echter dat de meeste situaties worden behandeld door een combinatie van de volgende hulpprogramma's en services te gebruiken:

We hebben het grootste succes in klantimplementaties gezien en raden de volgende procedures aan:

  • Stel GitHub - of Azure-opslagplaatsen in voor uw broncodebeheersysteem. Deze keuze bepaalt ook uw keuze voor pijplijnrunner. GitHub kan Gebruikmaken van Azure Pipelines of GitHub Actions, terwijl Azure-opslagplaatsen Azure Pipelines moeten gebruiken.
  • Stel een Azure API Management-service in voor elke API-ontwikkelaar, zodat ze SAMEN met de API-service API-definities kunnen ontwikkelen. Gebruik de verbruiks- of ontwikkelaars-SKU bij het maken van de service.
  • Gebruik beleidsfragmenten om het nieuwe beleid te verminderen dat ontwikkelaars voor elke API moeten schrijven.
  • Gebruik benoemde waarden en back-ends om ervoor te zorgen dat beleid algemeen is en kan worden toegepast op elk API Management exemplaar.
  • Gebruik de Azure APIOps Toolkit om een werkende API-definitie uit de ontwikkelaarsservice te extraheren.
  • Stel een API-goedkeuringsproces in dat voor elke pull-aanvraag wordt uitgevoerd. Het API-goedkeuringsproces moet detectie van wijzigingen die fouten veroorzaken, linting en geautomatiseerde API-tests omvatten.
  • Gebruik de uitgever van de Azure APIOps-toolkit om de API te publiceren naar uw productie-API Management-service.

Raadpleeg Geautomatiseerde API-implementaties met APIOps in het Azure Architecture Center voor meer informatie over het configureren en uitvoeren van een CI/CD-implementatiepijplijn met APIOps.

Referenties