Warum Sie ein API-Entwicklerportal für die API-Erkennung benötigen

Unternehmen verlassen sich zunehmend auf APIs, um Applications und Daten geschäftsbereichsübergreifend zu verbinden, die Integration mit Partnern vorzunehmen und Kundenerlebnisse zu bieten. Laut TechRadar nutzt das durchschnittliche Unternehmen heute insgesamt 15.564 APIs, eine Steigerung von 201 % im Vergleich zum Vorjahr .

Da die Anzahl der APIs weiter wächst , erhöht sich die Komplexität der Verwaltung Ihres API-Portfolios. Es wird schwieriger herauszufinden und zu verfolgen, welche APIs verfügbar sind und wo sie sich befinden. Außerdem ist es schwieriger, Dokumentationen zu ihrer Verwendung zu finden. Ohne eine ganzheitliche API-Strategie können sich APIs schneller vermehren, als Ihre Platform-Ops-Teams sie verwalten können. Wir bezeichnen dieses Problem als „API-Wildwuchs“ und haben in einem früheren Beitrag erklärt, warum es eine solch große Bedrohung darstellt. In diesem Beitrag gehen wir im Detail darauf ein, wie Sie der API-Ausbreitung entgegenwirken können, indem Sie mit Hilfe von NGINX ein API-Entwicklerportal einrichten.

Erstellen Sie ein Inventar Ihrer APIs

Letztendlich sind APIs erst dann nützlich, wenn sie verwendet werden. Das heißt, API-Verbraucher müssen eine Möglichkeit haben, sie zu finden. Ohne die richtigen Systeme wird es für Entwickler aufgrund der API-Ausbreitung schwierig, die APIs zu finden, die sie für ihre Applications benötigen. Bestenfalls werden API-Listen von verschiedenen Geschäftsbereichen geführt und Wissen wird über informelle Netzwerke von Ingenieuren zwischen Teams ausgetauscht.

Einer der ersten Schritte zur Bekämpfung der API-Ausbreitung ist die Schaffung einer einzigen zuverlässigen Quelle für Ihre APIs. Dieser Prozess beginnt mit der Erstellung eines Inventars Ihrer APIs. Eine genaue Bestandsaufnahme ist allerdings eine Herausforderung, denn das Ziel ändert sich ständig, da neue APIs eingeführt und alte verworfen werden. Sie müssen auch alle „Schatten-APIs“ in Ihren Umgebungen finden – APIs, die im Laufe der Zeit in Vergessenheit geraten sind, fälschlicherweise veraltet sind oder außerhalb Ihrer Standardprozesse erstellt wurden.

Nicht verwaltete APIs sind eines der heimtückischsten Symptome der API-Ausbreitung und bringen sowohl offensichtliche Auswirkungen auf die Sicherheit als auch versteckte Kosten mit sich. Ohne eine genaue Bestandsaufnahme der verfügbaren APIs müssen Ihre API-Teams viel Zeit mit der Suche nach Dokumentationen verbringen. Es besteht ein erhebliches Risiko, dass unnötiger Aufwand doppelt betrieben wird, da verschiedene Teams ähnliche Funktionen erstellen. Und Änderungen an einer bestimmten API können ohne ordnungsgemäße Versionskontrolle zu kostspieligen Nacharbeiten oder sogar Ausfällen führen.

Techniken wie die automatische API-Erkennung können Ihnen dabei helfen, die Symptome nicht verwalteter APIs zu identifizieren und zu behandeln. Doch um das Problem zu lösen, müssen Sie die Grundursache beseitigen: fehlerhafte Prozesse und fehlende Eigenverantwortung. In der Praxis ist die Integration des API-Inventars und der API-Dokumentation in Ihre CI/CD-Pipelines der einzige Ansatz, der langfristig Transparenz in Ihrem gesamten API-Portfolio gewährleistet. Anstatt jede API manuell verfolgen zu müssen, wenn sie online geht, müssen Sie nur Ausnahmen identifizieren und beheben.

Optimieren Sie die API-Erkennung mit einem API-Entwicklerportal

Ein API-Entwicklerportal kann beispielsweise bei der Optimierung der API-Erkennung hilfreich sein. Es bietet API-Verbrauchern einen zentralen Ort, um APIs zu entdecken, Dokumentationen zu lesen und APIs auszuprobieren, bevor sie sie in ihre Applications integrieren. Ihr API-Entwicklerportal kann auch als zentraler API-Katalog dienen, komplett mit Eigentümer- und Kontaktinformationen, sodass jeder weiß, wer für die Wartung der APIs für verschiedene Dienste verantwortlich ist.

Als Kernkomponente unserer API-Referenzarchitektur<.htmla> ermöglicht ein effektives API-Entwicklerportal einige wichtige Anwendungsfälle:

• Optimieren Sie die API-Erkennung – Veröffentlichen Sie Ihre APIs an einem zugänglichen Ort, damit Entwickler Ihre APIs leicht finden und in ihren Projekten verwenden können.
• Stellen Sie klare und aktuelle Dokumentation bereit – Stellen Sie sicher, dass Entwickler immer Zugriff auf die aktuellste Dokumentation zur Funktionsweise einer API haben.
• Stellen Sie eine ordnungsgemäße Versionierung sicher – Führen Sie neue Versionen einer API ein, ohne Ausfälle für nachgelagerte Applications zu verursachen, mit Unterstützung für die Versionierung
• API-Anmeldeinformationen generieren – Optimieren Sie den Onboarding-Prozess , sodass sich Entwickler anmelden und Anmeldeinformationen für den API-Zugriff generieren können
• APIs ausprobieren – Ermöglichen Sie Entwicklern, APIs auf dem Portal auszuprobieren, bevor sie diese in ihre Projekte integrieren

Als Teil Ihrer API-Strategie müssen Sie herausfinden, wie Sie Ihr API-Entwicklerportal pflegen. Sie benötigen einen automatisierten, unkomplizierten Ansatz, der die Veröffentlichung, Versionierung und Dokumentation von APIs nahtlos integriert, ohne Ihren API-Teams mehr Arbeit zu bereiten.

Erstellen Sie mit NGINX eine einzige Quelle der Wahrheit für Ihre APIs

Um eine nahtlose API-Erkennung zu ermöglichen, müssen Sie eine einzige zuverlässige Quelle erstellen, in der Entwickler Ihre APIs finden, ihre Verwendung erlernen und sie in ihre Projekte integrieren können. Das bedeutet, dass Sie ein Entwicklerportal und eine aktuelle Dokumentation benötigen.

API Connectivity Manager , Teil der F5 NGINX Management Suite, hilft Ihnen, die Veröffentlichung, Versionierung und Dokumentation von APIs direkt in Ihre Entwicklungs-Workflows zu integrieren, sodass Ihr API-Entwicklerportal nie veraltet ist. API Connectivity Manager vereinfacht nicht nur die Erstellung von API-Entwicklerportalen zum Hosten Ihrer APIs und Dokumentation, sondern ermöglicht Ihnen auch das Hinzufügen benutzerdefinierter Seiten und die vollständige Anpassung des Entwicklerportals an Ihr Branding.

Sehen wir uns an, wie der API Connectivity Manager Ihnen bei der Bewältigung einiger spezifischer Anwendungsfälle hilft. Ausführliche Anweisungen zum Einrichten eines Entwicklerportal-Clusters und zum Veröffentlichen eines Entwicklerportals finden Sie in der API Connectivity Manager-Dokumentation.

API-Dokumentation automatisch generieren

Zwischen der Qualität und dem Detailgrad, den Ihre API-Nutzer von der Dokumentation erwarten, und dem, was Ihre beschäftigten API-Entwickler mit begrenzter Zeit und Serverressourcen tatsächlich liefern können, klafft oft eine große Lücke. Viele selbst entwickelte Dokumentationstools integrieren sich nicht in den Anwendungslebenszyklus oder andere Engineering-Systeme. Sie müssen sich nicht mit dieser Situation abfinden.

Wie NGINX helfen kann: API Connectivity Manager verwendet die OpenAPI-Spezifikation , um APIs im API-Gateway zu veröffentlichen und automatisch die zugehörige Dokumentation auf dem Entwicklerportal zu generieren. Dies spart API-Entwicklern Zeit und stellt sicher, dass API-Verbraucher immer finden, was sie brauchen. Sie können OpenAPI-Spezifikationsdateien direkt über die Benutzeroberfläche des API Connectivity Managers hochladen oder indem Sie einen Anruf über die REST-API senden. Dies erleichtert die Automatisierung des Dokumentationsprozesses über Ihre CI/CD-Pipeline.

Um Dokumentation im API Connectivity Manager zu veröffentlichen, klicken Sie in der linken Navigationsspalte auf „Services“ , um die Registerkarte „Services“ zu öffnen. Klicken Sie auf den Namen Ihres Arbeitsbereichs oder erstellen Sie einen neuen .

Sobald Sie im Arbeitsbereich sind, klicken Sie unter dem Feld mit dem Namen und der Beschreibung Ihres Arbeitsbereichs ( Beispiel-API im Screenshot) auf „API-Dokumente“ . Klicken Sie einfach auf die Schaltfläche „API-Dokument hinzufügen“, um Ihre OpenAPI-Spezifikationsdatei hochzuladen. Klicken Sie auf die Schaltfläche „Speichern“ , um die Dokumentation im Entwicklerportal zu veröffentlichen.

Stellen Sie eine ordnungsgemäße Versionierung sicher

Versionsänderungen müssen immer mit Vorsicht behandelt werden. Dies gilt insbesondere in Microservices-Umgebungen, in denen viele Dienste möglicherweise mit einer einzigen API interagieren. Ohne einen sorgfältigen Ansatz bei der Einführung neuer Versionen und der Außerbetriebnahme alter Versionen kann eine einzige schwerwiegende Änderung zu einem kaskadierenden Ausfall bei Dutzenden von Microservices führen.

Wie NGINX helfen kann: Die Verwendung von OpenAPI-Spezifikationsdateien mit API Connectivity Manager ermöglicht eine einfache Versionskontrolle für Ihre APIs. Zusätzlich zum Festlegen der Versionsnummer können Sie Dokumentation für jede Version bereitstellen und ihren Status (neueste, aktive, außer Betrieb genommen oder veraltet) verwalten.

Um eine neue Version einer API zu veröffentlichen, klicken Sie in der linken Navigationsspalte auf „Dienste“ . Klicken Sie in der Tabelle auf den Namen Ihres Arbeitsbereichs und dann auf der sich öffnenden Seite auf den Namen Ihrer Umgebung. Klicken Sie anschließend auf die Schaltfläche + Proxy hinzufügen . Von hier aus können Sie die OpenAPI-Spezifikation hochladen, den Basispfad und die Version zum Erstellen der URI festlegen (z. B. /api/v2/ ) und andere wichtige Metadaten eingeben. Klicken Sie auf die Schaltfläche „Veröffentlichen“ , um Ihren API-Proxy zu speichern und zu veröffentlichen.

Die Originalversion der API bleibt neben Ihrer neuen Version verfügbar. So geben Sie Ihren Benutzern Zeit, ihre Applications oder Dienste schrittweise auf die neueste Version zu migrieren. Wenn Sie bereit sind, können Sie die ursprüngliche Version Ihrer API vollständig verwerfen. Abbildung 2 zeigt zwei veröffentlichte und in Produktion befindliche Versionen der Sentence Generator API.

API-Anmeldeinformationen generieren

Um die Akzeptanz Ihrer APIs zu fördern, müssen Sie den Onboarding-Prozess für Ihre API-Nutzer so einfach wie möglich gestalten. Sobald Benutzer ihre APIs gefunden haben, benötigen sie eine Methode, um sich sicher beim Entwicklerportal anzumelden und Anmeldeinformationen zu generieren. Mit diesen Anmeldeinformationen erhalten sie Zugriff auf die Funktionalität Ihrer API. In den meisten Fällen möchten Sie einen selbstverwalteten Workflow implementieren, damit sich Benutzer selbst anmelden können.

Wie NGINX Sie unterstützt: API Connectivity Manager ermöglicht selbstverwaltete API-Workflows im Entwicklerportal, sodass Sie eigene Ressourcenanmeldeinformationen zum Zugriff auf APIs erstellen können. Verwalten Sie Ressourcenanmeldeinformationen im Portal über API-Schlüssel oder HTTP-Basisauthentifizierung. Aktivieren Sie Single Sign-On (SSO) im Entwicklerportal, um den Zugang zu schützen und authentifizierten API-Nutzern die Verwaltung von Ressourcenanmeldeinformationen zu ermöglichen.

Um SSO im Entwicklerportal schnell zu aktivieren, klicken Sie in der linken Navigationsspalte auf „Infrastruktur“ . Klicken Sie in der Tabelle auf den Namen Ihres Arbeitsbereichs (in Abbildung 3 ist es „Team-Satz“ ).

Klicken Sie in der Tabelle auf der Seite „Arbeitsbereich“ auf den Namen der Umgebung, die Sie konfigurieren möchten (in Abbildung 4 ist dies „prod“ ).

Klicken Sie im Abschnitt „Entwicklerportal-Cluster“ auf das Symbol … in der Spalte „ Aktionen“ für das Entwicklerportal, an dem Sie arbeiten, und wählen Sie im Dropdownmenü „Erweiterte Konfiguration bearbeiten“ aus. In Abbildung 5 ist devportal-cluster der einzelne Developer Portal-Cluster .

Klicken Sie anschließend in der linken Navigationsspalte auf Globale Richtlinien . Konfigurieren Sie die OpenID Connect Relying Party -Richtlinie, indem Sie in der Spalte „Aktionen “ der Zeile auf das Symbol … klicken und im Dropdownmenü „Richtlinie bearbeiten“ auswählen. Weitere Informationen finden Sie in der API Connectivity Manager-Dokumentation .

APIs im Entwicklerportal ausprobieren

Sie können den Erfolg Ihrer API-Strategie unter anderem anhand der Kennzahl „Zeit bis zum ersten API-Aufruf“ messen. Diese gibt Aufschluss darüber, wie lange ein Entwickler braucht, um mit Ihrer API eine einfache Anfrage zu senden.

Wir haben festgestellt, dass eine klare, prägnante Dokumentation als erster Einstiegspunkt für Ihre API unerlässlich ist, da sie Ihren Benutzern ein grundlegendes Verständnis für die Arbeit mit einer API vermittelt. Normalerweise müssen Entwickler dann neuen Code schreiben, um die API in ihre Application zu integrieren, bevor sie API-Anfragen testen können. Sie können Entwicklern den Einstieg erleichtern, indem Sie ihnen die Möglichkeit bieten, unter Verwendung echter Daten direkt mit einer API auf dem Entwicklerportal zu interagieren. So können sie effektiv ihren ersten API-Aufruf tätigen, ohne eine einzige Codezeile für ihre Application schreiben zu müssen!

Wie NGINX helfen kann: Sobald Sie SSO für Ihre API Connectivity Manager-Entwicklerportale aktiviert haben, können API-Verbraucher den API Explorer verwenden, um API-Aufrufe auf Ihren Dokumentationsseiten auszuprobieren. Mit dem API Explorer können sie die Endpunkte, Parameter, Antworten und Datenmodelle der API erkunden und API-Aufrufe direkt mit ihrem Browser testen.

Abbildung 7 zeigt den API Explorer in Aktion – in diesem Fall beim Ausprobieren der Sentence Generator API. Der Benutzer wählt die entsprechenden Anmeldeinformationen aus, erstellt die Anfrage und erhält eine Antwort mit tatsächlichen Daten von der API.

Zusammenfassung

APIs sind für Ihr Unternehmen von entscheidender Bedeutung. Und der erste Schritt zur Verwaltung und Sicherung Ihrer APIs besteht darin, eine Bestandsaufnahme aller APIs zu machen, wo auch immer sie sich befinden. Aber die API-Erkennung ist nur ein Teil der Lösung – Sie müssen API-Inventar, -Dokumentation und -Versionierung in Ihren Entwicklungs- und Engineering-Lebenszyklus integrieren, um die Ursachen der API-Ausbreitung zu beheben.

Starten Sie eine 30-tägige kostenlose Testversion der NGINX Management Suite, die Zugriff auf API Connectivity Manager , NGINX Plus als API-Gateway und NGINX App Protect zum Sichern Ihrer APIs umfasst.