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

NGINX | 06. Dezember 2022

Unternehmen setzen zunehmend auf APIs, um Anwendungen und Daten über verschiedene Geschäftsbereiche hinweg zu verknüpfen, Partner anzubinden und Kundenerlebnisse bereitzustellen. Laut TechRadar nutzt ein durchschnittliches Unternehmen heute insgesamt 15.564 APIs – 201 % mehr als im Vorjahr.

Da die Anzahl der APIs weiter zunimmt, wird die Verwaltung Ihres API-Portfolios immer komplexer. Es wird schwieriger, verfügbare APIs zu finden und nachzuverfolgen, wo sie sich befinden, sowie Dokumentationen zu ihrer Verwendung ausfindig zu machen. Ohne eine ganzheitliche API-Strategie können sich APIs schneller ausbreiten, als Ihre Platform-Ops-Teams sie verwalten können. Wir bezeichnen dieses Problem als API-Wildwuchs und haben in einem früheren Beitrag erläutert, warum es eine so erhebliche Bedrohung darstellt. In diesem Beitrag untersuchen wir ausführlich, wie Sie API-Wildwuchs bekämpfen können, indem Sie mithilfe von NGINX ein API-Entwicklerportal einrichten.

Erstellen Sie ein Verzeichnis Ihrer APIs

Letztlich können APIs erst dann einen Nutzen entfalten, wenn sie verwendet werden – und dafür müssen API-Nutzer sie finden können. Ohne geeignete Systeme erschwert die unkontrollierte Verbreitung von APIs Entwicklern die Suche nach den APIs, die sie für ihre Anwendungen benötigen. Im besten Fall führen verschiedene Geschäftsbereiche eigene API-Listen, und Wissen wird über informelle Netzwerke von Entwicklern teamübergreifend weitergegeben.

Einer der ersten Schritte zur Eindämmung der API-Ausbreitung besteht darin, eine zentrale, verlässliche Informationsquelle für Ihre APIs zu schaffen. Dieser Prozess beginnt mit der Erstellung eines Verzeichnisses Ihrer APIs. Ein präzises Verzeichnis zu führen, ist jedoch eine Herausforderung, da es sich durch die Einführung neuer und die Außerbetriebnahme alter APIs ständig verändert. Außerdem müssen Sie in Ihren Umgebungen nach „Schatten-APIs“ suchen – also nach APIs, die im Laufe der Zeit in Vergessenheit geraten sind, nicht ordnungsgemäß außer Betrieb genommen wurden oder außerhalb Ihrer Standardprozesse entwickelt wurden.

Nicht verwaltete APIs gehören zu den heimtückischsten Symptomen einer unkontrollierten API-Ausbreitung und bergen sowohl offensichtliche Sicherheitsrisiken als auch versteckte Kosten. Ohne ein genaues Verzeichnis der verfügbaren APIs müssen Ihre API-Teams viel Zeit mit der Suche nach Dokumentationen verbringen. Zudem besteht ein erhebliches Risiko unnötiger Doppelarbeit, wenn verschiedene Teams ähnliche Funktionen entwickeln. Änderungen an einer bestimmten API können ohne eine ordnungsgemäße Versionskontrolle außerdem kostspielige Kaskaden von Nacharbeiten oder sogar Ausfälle verursachen.

Techniken wie die automatisierte API-Erkennung können Ihnen dabei helfen, das Symptom nicht verwalteter APIs zu erkennen und zu behandeln. Um das Problem jedoch zu lösen, müssen Sie die Ursachen beseitigen: fehlerhafte Prozesse und unklare Verantwortlichkeiten. In der Praxis ist die Integration des API-Bestands und der Dokumentation in Ihre CI/CD-Pipelines der einzige Ansatz, der langfristig Transparenz über Ihr gesamtes API-Portfolio gewährleistet. Anstatt jede API bei ihrer Inbetriebnahme manuell nachverfolgen zu müssen, brauchen Sie nur noch Ausnahmen zu identifizieren und zu beheben.

Optimieren Sie die API-Erkennung mit einem API-Entwicklerportal

Ein API-Entwicklerportal kann unter anderem dabei helfen, die API-Suche zu optimieren. Es bietet API-Nutzern eine zentrale Anlaufstelle, an der sie APIs finden, die Dokumentation lesen und APIs ausprobieren können, bevor sie diese in ihre Anwendungen integrieren. Ihr API-Entwicklerportal kann außerdem als zentraler API-Katalog dienen, der Angaben zu Zuständigkeiten und Kontaktdaten enthält, sodass jeder weiß, wer für die Pflege der APIs verschiedener Dienste verantwortlich ist.

Eine zentrale Komponente unserer API-Referenzarchitektur<.htmla>: Ein effektives API-Entwicklerportal ermöglicht einige wichtige Anwendungsfälle:

Im Rahmen Ihrer API-Strategie müssen Sie festlegen, wie Sie Ihr API-Entwicklerportal pflegen. Sie benötigen einen automatisierten, wartungsarmen Ansatz, der die Veröffentlichung, Versionierung und Dokumentation von APIs nahtlos integriert, ohne zusätzlichen Aufwand für Ihre API-Teams zu verursachen.

Schaffen Sie mit NGINX eine zentrale Informationsquelle für Ihre APIs

Um eine nahtlose API-Erkennung zu ermöglichen, müssen Sie eine zentrale Informationsquelle schaffen, in der Entwickler Ihre APIs finden, sich mit ihrer Verwendung vertraut machen und sie in ihre Projekte integrieren können. Dafür benötigen Sie ein Entwicklerportal – und eine aktuelle Dokumentation.

API Connectivity Manager, ein Bestandteil der F5 NGINX Management Suite, unterstützt Sie dabei, die Veröffentlichung, Versionierung und Dokumentation von APIs direkt in Ihre Entwicklungsworkflows zu integrieren, sodass Ihr API-Entwicklerportal stets auf dem neuesten Stand ist. API Connectivity Manager erleichtert nicht nur die Erstellung von API-Entwicklerportalen für die Bereitstellung Ihrer APIs und Dokumentation, sondern ermöglicht Ihnen auch, benutzerdefinierte Seiten hinzuzufügen und das Entwicklerportal vollständig an Ihr Branding anzupassen.

Sehen wir uns an, wie API Connectivity Manager Sie bei bestimmten Anwendungsfällen unterstützt. Ausführliche Anweisungen finden Sie in der Dokumentation zu API Connectivity Manager unter „Einrichten eines Entwicklerportal-Clusters“ und „Veröffentlichen eines Entwicklerportals“.

API-Dokumentation automatisch generieren

Zwischen der Qualität und Detailtiefe, die Ihre API-Nutzer von der Dokumentation erwarten, und dem, was Ihre stark ausgelasteten API-Entwickler mit begrenzter Zeit und knappen Ressourcen realistischerweise leisten können, klafft häufig eine große Lücke. Viele selbst entwickelte Dokumentationstools lassen sich nicht in den Entwicklungszyklus oder andere technische Systeme integrieren. Das muss nicht so sein.

So kann NGINX helfen: API Connectivity Manager verwendet die OpenAPI-Spezifikation, um APIs auf dem API-Gateway zu veröffentlichen und automatisch die zugehörige Dokumentation im Entwicklerportal zu erstellen. Das spart API-Entwicklern Zeit und stellt sicher, dass API-Nutzer stets finden, was sie benötigen. Sie können OpenAPI-Spezifikationsdateien direkt über die Benutzeroberfläche von API Connectivity Manager hochladen oder einen Aufruf über die REST-API senden. So lässt sich der Dokumentationsprozess ganz einfach über Ihre CI/CD-Pipeline automatisieren.

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 Workspace oder erstellen Sie einen neuen.

Wenn Sie sich im Workspace befinden, klicken Sie unterhalb des Feldes mit dem Namen und der Beschreibung Ihres Workspace (example-api im Screenshot) auf „API Docs“. Klicken Sie einfach auf die Schaltfläche „Add API Doc“, um Ihre OpenAPI-Spezifikationsdatei hochzuladen. Klicken Sie auf die Schaltfläche „Save“, um die Dokumentation im Entwicklerportal zu veröffentlichen.

Abbildung 1: Erstellen einer Dokumentation durch Hochladen einer OpenAPI-Spezifikationsdatei in den
API Connectivity Manager

Korrekte Versionierung sicherstellen

Versionsänderungen müssen stets mit Bedacht vorgenommen werden. Dies gilt insbesondere für Microservices-Umgebungen, in denen viele Dienste mit einer einzigen API interagieren können. Werden neue Versionen nicht sorgfältig eingeführt und alte Versionen nicht kontrolliert außer Betrieb genommen, kann eine einzige inkompatible Änderung zu einer Ausfallkaskade bei Dutzenden von Microservices führen.

So kann NGINX helfen: Durch die Verwendung von OpenAPI-Spezifikationsdateien mit API Connectivity Manager können Sie die Versionen Ihrer APIs ganz einfach verwalten. Neben der Festlegung der Versionsnummer können Sie für jede Version eine Dokumentation bereitstellen und ihren Status verwalten (neueste, aktiv, außer Betrieb genommen oder veraltet).

Um eine neue Version einer API zu veröffentlichen, klicken Sie in der linken Navigationsspalte auf „Services“. Klicken Sie in der Tabelle auf den Namen Ihres Workspace und anschließend auf der geöffneten Seite auf den Namen Ihrer Environment. Klicken Sie dann auf die Schaltfläche „+ Add Proxy“. Hier können Sie die OpenAPI-Spezifikation hochladen, den Basispfad und die Version festlegen, um den URI zu erstellen (zum Beispiel /api/v2/), und weitere wichtige Metadaten eingeben. Klicken Sie auf die Schaltfläche „Publish“, um Ihren API-Proxy zu speichern und zu veröffentlichen.

Die ursprüngliche Version der API bleibt parallel zu Ihrer neuen Version verfügbar. So haben Ihre Benutzer Zeit, ihre Anwendungen oder Dienste schrittweise auf die neueste Version zu migrieren. Wenn Sie so weit sind, können Sie die ursprüngliche Version Ihrer API vollständig außer Betrieb nehmen. Abbildung 2 zeigt zwei veröffentlichte und in Produktion befindliche Versionen der Sentence Generator API.

Abbildung 2: Verwalten aktiver API-Versionen im API Connectivity Manager

API-Anmeldedaten generieren

Um die Akzeptanz Ihrer APIs zu fördern, sollten Sie den Onboarding-Prozess für Ihre API-Nutzer so einfach wie möglich gestalten. Sobald Nutzer Ihre APIs gefunden haben, benötigen sie eine Möglichkeit, sich sicher beim Entwicklerportal anzumelden und Zugangsdaten zu generieren. Mit diesen Zugangsdaten erhalten sie Zugriff auf die Funktionen Ihrer API. In den meisten Fällen empfiehlt es sich, einen selbstverwalteten Workflow zu implementieren, damit sich Nutzer eigenständig registrieren können.

So kann NGINX helfen: API Connectivity Manager unterstützt selbstverwaltete API-Workflows im Entwicklerportal, sodass Benutzer ihre eigenen Ressourcenzugangsdaten für den Zugriff auf APIs generieren können. Ressourcenzugangsdaten können im Portal mithilfe von API-Schlüsseln oder HTTP-Basisauthentifizierung verwaltet werden. Sie können außerdem Single Sign-on (SSO) im Entwicklerportal aktivieren, um den Zugriff abzusichern und authentifizierten API-Nutzern die Verwaltung von Ressourcenzugangsdaten 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 dies „team-sentence“).

Abbildung 3: Liste der Workspaces auf der Registerkarte „Infrastructure“

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

Abbildung 4: Liste der Umgebungen in einem Workspace

Klicken Sie im Abschnitt „Developer Portal Clusters“ für das Entwicklerportal, an dem Sie gerade arbeiten, auf das Symbol „…“ in der Spalte „Actions“ und wählen Sie im Dropdown-Menü „Edit Advanced Config“ aus. In Abbildung 5 ist „devportal-cluster“ der einzige Developer Portal Cluster.

Abbildung 5: Auswählen der Option „Edit Advanced Config“ für einen Entwicklerportal-Cluster

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

Abbildung 6: Konfigurieren der globalen OpenID-Connect-Relying-Party-Richtlinie zum Aktivieren von Single Sign-on

APIs im Entwicklerportal ausprobieren

Eine Möglichkeit, den Erfolg Ihrer API-Strategie zu messen, besteht darin, die Kennzahl „Zeit bis zum ersten API-Aufruf“ zu erfassen. Sie gibt Aufschluss darüber, wie lange ein Entwickler benötigt, um eine einfache Anfrage an Ihre API zu senden.

Wir haben festgestellt, dass eine klare, prägnante Dokumentation als erster Einstiegspunkt für Ihre API unerlässlich ist. Dort erhalten Ihre Benutzer ein grundlegendes Verständnis dafür, wie sie mit einer API arbeiten. In der Regel müssen Entwickler anschließend neuen Code schreiben, um die API in ihre Anwendung zu integrieren, bevor sie API-Anfragen testen können. Sie können Entwicklern einen deutlich schnelleren Einstieg ermöglichen, indem Sie ihnen die Möglichkeit bieten, im Entwicklerportal anhand realer Daten direkt mit einer API zu interagieren. So können sie ihren ersten API-Aufruf durchführen, ohne eine einzige Zeile Code für ihre Anwendung schreiben zu müssen!

So kann NGINX helfen: Sobald Sie SSO für Ihre Entwicklerportale im API Connectivity Manager aktiviert haben, können API-Nutzer mit dem API Explorer API-Aufrufe auf Ihren Dokumentationsseiten ausprobieren. Mit dem API Explorer können sie die Endpunkte, Parameter, Antworten und Datenmodelle der API erkunden und API-Aufrufe direkt in 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 Anmeldedaten aus, erstellt die Anfrage und erhält eine Antwort mit tatsächlichen Daten von der API.

Abbildung 7: Testen einer API im Entwicklerportal

Zusammenfassung

APIs sind für Ihr Unternehmen von entscheidender Bedeutung. Der erste Schritt zur Verwaltung und Absicherung Ihrer APIs besteht darin, sämtliche APIs zu erfassen – unabhängig davon, wo sie sich befinden. Doch die API-Erkennung ist nur ein Teil der Lösung: Sie müssen die Inventarisierung, Dokumentation und Versionierung von APIs in Ihren Entwicklungs- und Engineering-Lebenszyklus integrieren, um die Ursachen der unkontrollierten Ausbreitung von APIs zu bekämpfen.

Starten Sie eine kostenlose 30-Tage-Testversion der NGINX Management Suite, die Zugriff auf den API Connectivity Manager, NGINX Plus als API-Gateway und NGINX App Protect zur Absicherung Ihrer APIs umfasst.