Wie man Breaking API Changes mit API Gateway verhindert

Wenn Sie APIs entwickeln, ändern Sie manchmal Dinge, die Probleme für aktuelle API-Nutzer verursachen könnten. Die Weiterentwicklung Ihrer API ohne Auswirkungen auf aktuelle Benutzer ist entscheidend, da sie sonst das Vertrauen in Ihr Angebot verlieren könnten. Es ist unmöglich, diese Probleme vollständig zu vermeiden, aber Sie können die Auswirkungen minimieren oder einige kritische Änderungen erkennen, bevor sie eintreten. Breaking Changes müssen während der Entwicklungsphase identifiziert werden, und wenn sie auftreten, sollte das API-Gateway sie handhaben, um sicherzustellen, dass Client-Anwendungen nicht beeinträchtigt werden. In diesem Artikel werden wir einige Best Practices und Strategien untersuchen, um API-Breaking Changes zu verhindern und wie man sie mit dem APISIX API-Gateway handhabt.

Was sind API-Breaking Changes?

Softwareprodukte entwickeln sich ständig weiter, und ihre APIs sind keine Ausnahme. Diese APIs dienen als primäre Schnittstelle, über die externe API-Nutzer mit Ihrem System interagieren, und spiegeln alle Produktänderungen wider. Es gibt verschiedene Gründe für diese API-Änderungen, darunter technologische Verbesserungen, Änderungen in der Geschäftsausrichtung, kritische Fehlerbehebungen und mehr. Einfach ausgedrückt ist ein Breaking Change, wenn Sie Ihre API ändern und dies Probleme für Client-Anwendungen verursachen könnte, die sie verwenden. Einige dieser Änderungen sind leichter zu erkennen als andere. Hier sind einige Beispiele für Breaking Changes:

Entfernen eines Endpunkts: Wenn Sie einen GET /users-Endpunkt haben und diesen entfernen, erhalten alle Clients, die darauf zugreifen möchten, Fehler.
Ändern der URL eines Endpunkts: Wenn Sie die URL eines Endpunkts von GET /users auf GET /members ändern, haben Clients, die die alte URL verwenden, Probleme.
Ändern des Request-Payloads: Wenn ein Endpunkt bestimmte Daten in der Anfrage erwartet, wie z.B. POST /users, das { "name": "John" } erwartet, Sie aber die Anforderung auf { "firstName": "John" } ändern, wird dies Clients stören, die das alte Format senden.
Entfernen oder Umbenennen von Feldern in der Antwort: Wenn Clients bestimmte Felder in der API-Antwort erwarten, führt das Entfernen oder Umbenennen dieser Felder dazu, dass diese Clients nicht mehr funktionieren. Zum Beispiel die Änderung von { "id": 1, "name": "John" } zu { "id": 1, "fullName": "John Doe" }.
Ändern von Datentypen: Wenn ein API-Feld als Zeichenkette erwartet wird und Sie es in eine Ganzzahl oder einen anderen Typ ändern, kann dies Clients beeinträchtigen. Zum Beispiel die Änderung von "age": "25" zu "age": 25.
Ändern von Authentifizierungsmechanismen: Wenn Sie von der Basisauthentifizierung auf tokenbasierte Authentifizierung umstellen, ohne einen ordnungsgemäßen Übergang zu gewährleisten, werden bestehende Clients Authentifizierungsfehler erhalten.
Einführen von Pflichtfeldern: Wenn Sie einen Endpunkt wie POST /users haben, der optionale Felder akzeptiert, und Sie plötzlich eines dieser Felder als Pflichtfeld festlegen, werden bestehende Clients, die dieses Feld nicht senden, Probleme haben.
Ändern von Fehlerformaten: Wenn Clients darauf programmiert sind, bestimmte Fehlerformate zu verstehen, kann die Änderung dieser Formate zu einer falschen Fehlerbehandlung auf der Client-Seite führen.
Ändern von HTTP-Statuscodes: Die Änderung der Statuscodes für bestimmte Operationen, wie z.B. die Rückgabe eines 200 OK anstelle eines 201 Created für die Ressourcenerstellung, kann Clients in die Irre führen.
Einstellen der Unterstützung für ältere API-Versionen: Wenn Sie die Unterstützung für ältere Versionen ohne eine angemessene Übergangsphase einstellen, werden Clients, die auf diese älteren Versionen angewiesen sind, nicht mehr funktionieren.

Jede Änderung an einer API hat das Potenzial, eine Client-Anwendung zu beeinträchtigen. Wenn Sie ein API-Gateway wie eine Eingangstür für alle Backend-APIs verwenden, weiß das Gateway, wohin die Anfrage basierend auf einer Reihe von Regeln, die in einer Routenkonfiguration definiert sind, weitergeleitet werden soll, und es ist der richtige Ort, um API-Breaking Changes zu handhaben. Lassen Sie uns sehen, wie wir APISIX verwenden können, um einige API-Änderungen zu identifizieren.

Validierung von Request- und Response-Schemata

Die Definition strenger Schemata für Ihre Routen ermöglicht es Ihnen, sicherzustellen, dass die Strukturen von Anfragen und Antworten wie erwartet sind. Verwenden Sie das request-validation-Plugin, um eingehende Anfragen zu validieren, und das response-rewrite-Plugin, um die API-Antwort basierend auf bestimmten Bedingungen umzuschreiben.

Protokollierung

APISIX unterstützt verschiedene Protokollierungs-Plugins wie http-logger, elasticsearch-logger, file-logger und mehr. Richten Sie einen Logger ein, um die API-Anfrage- und Antwortdaten zu speichern, und analysieren Sie die Protokolle regelmäßig, um Änderungen in den Anfrage-/Antwort-Headern, Payload-Strukturen oder anderen ungewöhnlichen Mustern zu erkennen.

Überwachung von Routen und Upstreams

Überwachen Sie die Routen, die durch das Gateway gehen. Wenn eine zuvor verfügbare Route plötzlich 404-Fehler zurückgibt, ist dies ein potenzielles Zeichen dafür, dass die API geändert wurde oder ein Endpunkt eingestellt wurde. Aktivieren Sie die API-Gesundheitsüberprüfung, um kontinuierlich den allgemeinen Zustand der Upstream-Knoten zu überwachen. Wenn einer der Knoten beginnt, langsamer oder schneller als üblich zu reagieren, könnte dies auf eine Änderung in der Verarbeitung des zugrunde liegenden Backend-Dienstes hinweisen. Integrieren Sie APISIX mit Überwachungstools wie Prometheus unter Verwendung des prometheus-Plugins. Richten Sie Warnungen basierend auf Metriken ein, wie z.B. eine erhöhte Rate von 4xx- oder 5xx-Fehlern, die auf Breaking Changes in Ihrer API hinweisen könnten.

Verwendung von Versionierung

API-Versionierung ist die Praxis, Änderungen an einer API zu verwalten und sicherzustellen, dass diese Änderungen vorgenommen werden, ohne API-Consumer-Apps zu stören. Es gibt verschiedene Methoden, um Versionierung mit APISIX einzurichten, wie z.B. die Verwendung von URI-Pfaden, Abfrageparametern, Headern oder die Auswahl des Inhaltstyps. Zum Beispiel könnten Sie Webadressen wie /v1/users oder /v2/users haben, um die Version Ihrer API anzuzeigen. Durch diese Versionen können Sie mehr als eine Option Ihrer API anbieten, und API-Consumer können in ihrem eigenen Tempo auf die neueste Version upgraden. APISIX kann den gesamten Verkehr leicht auf die alte, stabile Version der API zurückleiten, bis Sie die Probleme in der neuen Version behoben haben, die Ihre APIs rückwärtskompatibel machen. Verwenden Sie APISIX, um die alte Kompatibilität beizubehalten, während Sie die neuen Änderungen einführen. Wenn Sie Probleme in der neuen Version feststellen, ermöglicht das traffic-split-Plugin ein schnelles Rollback.

Abkündigungshinweise

Bevor Sie Funktionen entfernen oder ändern, kennzeichnen Sie sie als veraltet, um den Consumern ausreichend Zeit zur Anpassung zu geben. Mit Hilfe von APISIX können wir die Route so konfigurieren, dass sie über ihre zukünftige Abkündigung und ihren Ersatz informiert. Dafür bietet APISIX das response-rewrite-Plugin.

Integration mit Versionskontrolle

Während Sie vielleicht wünschen, dass Pull-Request-Prüfer alle Breaking Changes erkennen, ist es nicht sicher, sich allein auf diese Methode zu verlassen, und könnte schließlich zu einem Fehler führen. Wenn Sie OpenAPI/Swagger-Dokumentation für Ihre APIs haben, können diese versionskontrolliert und in eine CI-Pipeline integriert werden. APISIX unterstützt keine native Integration mit Versionskontrollsystemen wie Git für API-Spezifikationsänderungen. Sie können jedoch einen Prozess außerhalb von APISIX einrichten. Tools wie Oasdiff oder Bump können Änderungen in API-Spezifikationen identifizieren und eine CI-Pipeline auslösen (fügen Sie GitHub Action hinzu), die Tests gegen die Routenendpunkte in APISIX durchführt, um sicherzustellen, dass keine Breaking Changes eingeführt werden.

api-breaking-changes-detector-git

Andere Möglichkeiten zur Erkennung von Änderungen

Postman enthält eine Vorlage, um automatisch die aktuelle Version Ihrer API auf Breaking Changes zu überprüfen, und beschreibt, wie sie in diesem Artikel funktioniert. Sie fügen den Detektor als zusätzlichen Schritt in die CI-Pipeline ein. Jedes Mal, wenn Ihre Pipeline ausgeführt wird, analysiert der Breaking-Change-Detektor die aktuelle API-Spezifikation gegen die vorherige und benachrichtigt Sie über alle Unterschiede. Abhängig von Ihrem Entwicklungsstack gibt es andere Bibliotheken, um OpenAPI-Spezifikationen zu vergleichen. Dieser Artikel erklärt gut, wie man sie in der Praxis mit getesteten Bereitstellungsstrategien erkennt, bevor neue Änderungen in die Produktion übernommen werden.

Zusammenfassung

Die Erkennung und Verhinderung von API-Breaking Changes ist wichtig, um das Vertrauen der API-Consumer zu erhalten und den Erfolg Ihres Dienstes sicherzustellen. Durch die Integration der Fähigkeiten von APISIX wie Request-Validierung, Versionierung, Protokollierung, Überwachung und Alarmierung mit Techniken wie automatisierten API-Vertragstests können Sie sicherstellen, dass Ihre APIs sich weiterentwickeln, ohne Ihre Clients negativ zu beeinflussen.