Verwenden Sie DevOps und CI/CD, um APIs zu veröffentlichen

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Angesichts des strategischen Werts von APIs im Unternehmen ist die Einführung von DevOps-Techniken für kontinuierliche Integration (CI) und Bereitstellung (CD) zu einem wichtigen Aspekt der API-Entwicklung geworden. In diesem Artikel werden die Entscheidungen erörtert, die Sie treffen müssen, um DevOps-Prinzipien für die Verwaltung von APIs zu übernehmen.

API DevOps besteht aus drei Teilen:

Diagramm, das den API-DevOps-Fluss veranschaulicht.

Jeder Teil der API DevOps-Pipeline wird unten besprochen.

API-Definition

Ein API-Entwickler schreibt eine API-Definition, indem er eine Spezifikation, Einstellungen (z. B. Protokollierung, Diagnose und Backend-Einstellungen) und Richtlinien bereitstellt, die auf die API angewendet werden sollen. Die API-Definition stellt die Informationen bereit, die zum Bereitstellen der API in einem Azure API Management-Dienst erforderlich sind. Die Spezifikation kann auf einer standardbasierten API-Spezifikation (z. B. WSDL, OpenAPI oder GraphQL) basieren oder mithilfe der Azure Resource Manager (ARM)-APIs definiert werden (z. B. eine ARM-Vorlage, die die API und Vorgänge beschreibt). Die API-Definition wird sich im Laufe der Zeit ändern und sollte als „Quellcode“ betrachtet werden. Stellen Sie sicher, dass die API-Definition unter Quellcodekontrolle gespeichert ist und vor der Übernahme angemessen überprüft wird.

Es gibt mehrere Tools, die bei der Erstellung der API-Definition helfen:

  • Das Azure APIOps-Toolkit stellt einen Workflow bereit, der auf einem Git-Quellcodeverwaltungssystem (wie GitHub oder Azure Repos) aufbaut. Es verwendet einen Extraktor, um eine API-Definition zu erzeugen, die dann von einem Herausgeber auf einen API Management-Zieldienst angewendet wird. APIOps unterstützt derzeit REST- und GraphQL-APIs.
  • Das dotnet-apim-Tool konvertiert eine wohlgeformte YAML-Definition in eine ARM-Vorlage für die spätere Bereitstellung. Das Tool konzentriert sich auf REST-APIs.
  • Terraform ist eine Alternative zu Azure Resource Manager, um Ressourcen in Azure zu konfigurieren. Sie können eine Terraform-Konfiguration (zusammen mit Richtlinien) erstellen, um die API auf die gleiche Weise zu implementieren, wie eine ARM-Vorlage erstellt wird.

Sie können auch IDE-basierte Tools für Editoren wie Visual Studio Code verwenden, um die Artefakte zu erstellen, die zum Definieren der API erforderlich sind. Beispielsweise gibt es auf dem Visual Studio Code Marketplace über 30 Plug-ins zum Bearbeiten von OpenAPI-Spezifikationsdateien. Sie können auch Codegeneratoren verwenden, um die Artefakte zu erstellen. Mit der CADL-Sprache können Sie auf einfache Weise High-Level-Bausteine erstellen und diese dann in ein Standard-API-Definitionsformat wie OpenAPI kompilieren.

API-Zulassung

Sobald die API-Definition erstellt wurde, reicht der Entwickler die API-Definition zur Überprüfung und Genehmigung ein. Wenn Sie ein Git-basiertes Quellcodeverwaltungssystem (wie GitHub oder Azure Repos) verwenden, kann die Übermittlung per Pull Anforderung erfolgen. Eine Pull-Anforderung informiert andere über Änderungen, die an der API-Definition vorgeschlagen wurden. Sobald die Genehmigungs-Gates bestätigt wurden, führt ein Genehmiger die Pull-Anforderung in das Haupt-Repository ein, um zu signalisieren, dass die API-Definition in der Produktion bereitgestellt werden kann. Der Pull-Anforderung-Prozess befähigt den Entwickler, alle Probleme zu beheben, die während des Genehmigungsprozesses gefunden wurden.

Sowohl GitHub als auch Azure Repos ermöglichen die Konfiguration von Genehmigungspipelines, die ausgeführt werden, wenn eine Pull-Anforderung gesendet wird. Sie können die Genehmigungspipelines so konfigurieren, dass sie Tools wie die folgenden ausführen:

  • API-Spezifikations-Linters wie Spectral, um sicherzustellen, dass die Definition den von der Organisation geforderten API-Standards entspricht.
  • Erkennung von Breaking Changes mit Tools wie openapi-diff.
  • Tools für Sicherheitsaudits und -bewertungen. OWASP verwaltet eine Liste von Tools für Sicherheitsscans.
  • Automatisierte API-Testframeworks.

Hinweis

Azure-APIs müssen strengen Richtlinien entsprechen, die Sie als Ausgangspunkt für Ihre eigenen API-Richtlinien verwenden können. Es gibt eine Spectral-Konfiguration zur Durchsetzung der Richtlinien.

Sobald die automatisierten Tools ausgeführt wurden, wird die API-Definition vom menschlichen Auge überprüft. Tools werden nicht alle Probleme abfangen. Ein menschlicher Prüfer stellt sicher, dass die API-Definition die organisatorischen Kriterien für APIs erfüllt, einschließlich der Einhaltung von Sicherheits-, Datenschutz- und Konsistenzrichtlinien.

API-Veröffentlichung

Die API-Definition wird über eine Release-Pipeline an einen API Management-Dienst veröffentlicht. Die zum Veröffentlichen der API-Definition verwendeten Tools hängen von dem Tool ab, das zum Erstellen der API-Definition verwendet wurde:

Kann ich andere Quellcodeverwaltungs- und CI/CD-Systeme verwenden?

Ja. Der beschriebene Prozess funktioniert mit jedem Quellcode-Kontrollsystem (obwohl APIOps erfordert, dass das Quellcode-Kontrollsystem Git-basiert ist). Ebenso können Sie jede CI/CD-Plattform verwenden, solange sie durch ein Einchecken ausgelöst werden kann, und Befehlszeilentools ausführen, die mit Azure kommunizieren.

Bewährte Methoden

Es gibt keinen Industriestandard zum Einrichten einer DevOps-Pipeline zum Veröffentlichen von APIs, und keines der genannten Tools funktioniert in allen Situationen. Wir sehen jedoch, dass die meisten Situationen durch die Verwendung einer Kombination der folgenden Tools und Dienste abgedeckt werden:

Wir haben den größten Erfolg bei Kundenbereitstellungen festgestellt und empfehlen die folgenden Vorgehensweisen:

  • Richten Sie entweder GitHub oder Azure Repos für Ihr Quellcodeverwaltungssystem ein. Diese Wahl bestimmt auch Ihre Wahl des Pipeline-Runners. GitHub kann Azure Pipelines oder GitHub Actions verwenden, während Azure Repos Azure Pipelines verwenden muss.
  • Richten Sie für jeden API-Entwickler einen Azure API Management-Dienst ein, damit er zusammen mit dem API-Dienst API-Definitionen entwickeln kann. Verwenden Sie beim Erstellen des Diensts die Verbrauchs- oder Entwickler-SKU.
  • Verwenden Sie Richtlinienfragmente, um die neue Richtlinie zu reduzieren, die Entwickler für jede API schreiben müssen.
  • Verwenden Sie benannte Werte und Back-Ends, um sicherzustellen, dass Richtlinien generisch sind und auf jede API Management-Instanz angewendet werden können.
  • Verwenden Sie das Azure APIOps-Toolkit, um eine funktionierende API-Definition aus dem Entwicklerdienst zu extrahieren.
  • Richten Sie einen API-Genehmigungsprozess ein, der bei jeder Pull-Anforderung ausgeführt wird. Der API-Genehmigungsprozess sollte Breaking Change Detection, Linting und automatisierte API-Tests umfassen.
  • Verwenden Sie den Azure APIOps-Toolkit-Herausgeber, um die API in Ihrem API Management-Produktionsdienst zu veröffentlichen.

Weitere Informationen zum Konfigurieren und Ausführen einer CI/CD-Bereitstellungspipeline mit APIOps finden Sie unter Automatisierte API-Bereitstellungen mit APIOps im Azure Architecture Center.

References