Die richtige Herangehensweise: Code-First oder Design-First für APIs?

Um eine optimale Nutzung unserer APIs zu gewährleisten, hat sich Amazons API Gateway als Instrument zur Skalierung, Erstellung und Verwaltung von APIs etabliert.

Herausforderungen bei der Konsistenz:

Eine große Herausforderung, die Benutzer bei der Verwendung eines API Gateways meistern müssen, ist das Fehlen von Konsistenz und Standardisierung im gesamten API-Erlebnis. Dies tritt häufig in großen Organisationen auf, in denen mehrere Teams für die Wartung eines komplexen API-Ökosystems zuständig sind. Die Folge ist ein unlogisch und unvorhersehbares API-Erlebnis, welches die Akzeptanz und Nutzung der APIs negativ beeinflusst.

Die Bedeutung korrekter Dokumentation:

Um ein umfangreiches API-Netzwerk effektiv zu verwalten, müssen wir zunächst unsere APIs dokumentieren – und zwar korrekt. Einige API-Design-Tools wie SwaggerHub von SmartBear ermöglichen es uns, die API in das Tool zu importieren und den Code automatisch zu analysieren, um die Dokumentation zu erstellen. SwaggerHub bietet darüber hinaus viele weitere Funktionen, mit denen Entwickler APIs designen, entwickeln und dokumentieren können. Mit Hilfe der OpenAPI Specification (früher bekannt als Swagger) können Benutzer benutzerdefinierte Regeln erstellen, um sicherzustellen, dass alle APIs demselben Standard entsprechen.

Code-First vs. Design-First: Die Entscheidung:

Die Wahl zwischen Code-First oder Design-First ist nicht immer einfach. Das Ziel sollte sein, die APIs so effizient wie möglich zu dokumentieren und zu standardisieren. Manche Projekte erfordern einen Code-First Ansatz, während andere einen Design-First Ansatz bevorzugen. Code-First eignet sich hervorragend für einen schnellen Start und den Aufbau einer Anwendung von Grund auf. Da die Dokumentation aus dem Code generiert wird, ist sie stets aktuell. Möglicherweise fehlen jedoch Inhalte oder Kontext in der Dokumentation.

Da der Fokus auf dem Code liegt, kann es an Detailreichtum oder 100%iger Korrektheit mangeln. Design-First hingegen zeichnet sich durch höhere Klarheit und Anleitung in der API-Dokumentation aus und verbessert damit die Zusammenarbeit und Akzeptanz der API. Auch wenn der anfängliche Aufwand für die Dokumentation vor der Implementierung nicht immer gerechtfertigt ist, besteht die Gefahr einer Diskrepanz zwischen Dokumentation und Funktionalität, die als API Drift bezeichnet wird.

Die gute Nachricht:

Es gibt keine Einschränkung bei der Verwendung eines Ansatzes gegenüber dem anderen. Bei korrekter Anwendung können wir ein konsistentes API-Erlebnis für alle Benutzer gewährleisten. Durch die Nutzung des am häufigsten verwendeten Gateways können wir das API-Erlebnis für Endbenutzer in Echtzeit verfolgen und bei Bedarf anpassen.

Integration von Code-First mit Amazon API Gateway und SwaggerHub:

Nun ist es Zeit, die API zu dokumentieren. Unsere API ist bereits auf einem API Gateway gehostet. Gehen Sie zu der API, die wir standardisieren oder dokumentieren möchten, und veröffentlichen Sie die Dokumentation (die API muss bereitgestellt werden, um die Dokumentation zu veröffentlichen).

Import der API in SwaggerHub:

Nachdem die API importiert wurde, führt SwaggerHub automatisch eine Standardvalidierung der OpenAPI Specification durch, um sicherzustellen, dass die API korrekt ist, und alle benutzerdefinierten Regeln aktiviert sind.

Weitere Vorteile von SwaggerHub:

SwaggerHub bietet zahlreiche weitere Vorteile, die nahtlos mit jedem API Gateway zusammenarbeiten. SwaggerHub Domains bietet einen zentralen Ort zur Verwaltung gemeinsamer Komponenten von APIs wie Schemas, Sicherheitsdefinitionen und Antworten. Durch die Verwendung von Domains können API-Entwickler diese Komponenten einmal erstellen und in mehreren APIs wiederverwenden, was doppelte Arbeit vermeidet, eine einheitliche Gestaltung gewährleistet, Fehler minimiert und die API-Entwicklung beschleunigt.

Automatisierung der Integration:

Sowohl Amazon API Gateway als auch SwaggerHub verfügen über Kommandozeilen-Schnittstellen, um diese Integration zu automatisieren. Die Voraussetzung dafür ist der Download und die Konfiguration der erforderlichen Kommandozeilen-Schnittstellen von AWS und SwaggerHub. Im ersten Schritt des Pipelines exportieren wir eine REST-API aus dem API Gateway mithilfe der AWS CLI. Anschließend erstellen wir mit der SwaggerHub CLI die API in SwaggerHub. Sobald sich die API in SwaggerHub befindet, analysieren die API-Validierungen und benutzerdefinierten Richtlinien automatisch die API-Spezifikation, um ein konsistentes API-Erlebnis zu gewährleisten.

Design-First mit Amazon API Gateway und SwaggerHub:

Die Design-First API-Methode wird eingesetzt, um kurzfristig Geschwindigkeit und langfristig Konsistenz zu umsetzen. Die Konsistenz und der Standard, den Design-First bietet, sind die Hauptgründe, warum die meisten neuen APIs auf diese Weise erstellt werden.

Zusammenfassend:

Es gibt kein Richtig oder Falsch bei Code-First oder Design-First. Beide Methoden haben ihre Vorzüge und Möglichkeiten der Fehlanpassung. Die beste Lösung für die API-Dokumentation besteht darin, korrekt zu dokumentieren – unabhängig davon, ob Teams den Anwendungscode zuerst erstellen oder die Dokumentation zuerst entwickeln. Wenn wir korrekt dokumentieren, wird die Möglichkeit einer Fehlanpassung minimiert. Auf höherer Ebene können wir mit Amazon API Gateway und SwaggerHub ein umfangreiches Netzwerk von APIs effektiv verwalten. Die Kombination dieser beiden Tools ermöglicht es uns, den Endbenutzern unserer APIs eine reichhaltige, gut dokumentierte API mit Beispielen zu bieten, die auf der niedrigsten Latenz gehostet wird und flexible Sicherheits- und Überwachungsfunktionen bietet.