Delen via

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

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Met de strategische waarde van API's in de onderneming is het aannemen 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 dat de API DevOps-stroom illustreert.

Elk deel 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 op de API moeten worden toegepast. 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 API-specificatie op basis van standaarden (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 wordt na verloop van tijd gewijzigd en moet worden beschouwd als 'broncode'. Zorg ervoor dat de API-definitie wordt opgeslagen onder broncodebeheer en de juiste beoordeling heeft voordat de api wordt geïmplementeerd.

Er zijn verschillende hulpprogramma's waarmee u de API-definitie kunt maken:

  • De Azure APIOps Toolkit biedt een werkstroom die is gebouwd op basis van 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 MOMENTEEL REST- en GraphQL-API's.
  • Het hulpprogramma dotnet-apim converteert een goed opgemaakte 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 voor het configureren van resources in Azure. U kunt een Terraform-configuratie (samen met beleid) maken om de API op dezelfde manier te implementeren als een ARM-sjabloon.

U kunt ook hulpprogramma's op basis van IDE gebruiken voor editors zoals Visual Studio Code 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 voor beoordeling en goedkeuring. Als u een broncodebeheersysteem op basis van Git (zoals GitHub of Azure-opslagplaatsen) gebruikt, kan de inzending worden uitgevoerd via een pull-aanvraag. Een pull-aanvraag informeert anderen over wijzigingen die zijn voorgesteld voor 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. Met het pull-aanvraagproces kan de ontwikkelaar eventuele problemen oplossen die tijdens het goedkeuringsproces zijn gevonden.

In zowel GitHub als Azure-opslagplaatsen kunnen goedkeuringspijplijnen worden geconfigureerd die worden uitgevoerd wanneer een pull-aanvraag wordt ingediend. U kunt de goedkeuringspijplijnen configureren om hulpprogramma's uit te voeren, zoals:

  • API-specificatie linters zoals Spectral om ervoor te zorgen dat de definitie voldoet aan API-standaarden die door de organisatie zijn vereist.
  • Detectie van wijzigingen die fouten veroorzaken met behulp van hulpprogramma's zoals openapi-diff.
  • Hulpprogramma's voor beveiligingscontrole en -evaluatie. OWASP onderhoudt een lijst met hulpprogramma's voor het scannen van beveiliging.
  • Geautomatiseerde API-testframeworks zoals Newman, een testloper voor Postman-verzamelingen.

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 beoordeeld door het menselijke oog. Hulpprogramma's vangen niet alle problemen op. Een menselijke revisor zorgt ervoor dat de API-definitie voldoet aan de organisatiecriteria voor API's, waaronder naleving van beveiligings-, privacy- en consistentierichtlijnen.

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 git is). Op dezelfde manier kunt u elk CI/CD-platform gebruiken zolang het kan worden geactiveerd door een check-in en opdrachtregelprogramma's uit te voeren die communiceren met Azure.

Aanbevolen procedures

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

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

  • Stel GitHub of Azure-opslagplaatsen in voor uw broncodebeheersysteem. Deze keuze bepaalt ook uw keuze voor pijplijnloper. GitHub kan Azure Pipelines of GitHub Actions gebruiken, terwijl Azure-opslagplaatsen Azure Pipelines moeten gebruiken.
  • Stel een Azure API Management-service in voor elke API-ontwikkelaar, zodat ze API-definities samen met de API-service kunnen ontwikkelen. Gebruik de verbruiks- of ontwikkelaars-SKU bij het maken van de service.
  • Gebruik beleidsfragmenten om het nieuwe beleid te verminderen dat ontwikkelaars moeten schrijven voor elke API.
  • 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 te extraheren uit de ontwikkelaarsservice.
  • Stel een API-goedkeuringsproces in dat wordt uitgevoerd op elke pull-aanvraag. Het API-goedkeuringsproces moet betrekking hebben op wijzigingsdetectie, linting en geautomatiseerde API-tests.
  • Gebruik de Uitgever van de Azure APIOps Toolkit om de API te publiceren naar uw productie-API Management-service.

Bekijk 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.

Verwijzingen