Sollte man generell eine Clientbibliothek für REST-Services entwickeln, um API-Brüche zu vermeiden?

9

Wir haben ein Projekt, in dem UI-Code vom selben Team entwickelt wird, jedoch in einer anderen Sprache (Python / Django) als die Serviceschicht (REST / Java). Der Code für jede Schicht Exits in verschiedenen Code - Repositories und welche können unterschiedliche Freisetzungszyklen folgen. Ich versuche, einen Prozess zu entwickeln, der das Brechen von Änderungen in der Serviceschicht aus Sicht der UI-Schicht verhindert / reduziert.

Ich habe mir überlegt, Integrationstests auf der Ebene der Benutzeroberfläche zu schreiben, die wir ausführen, wenn wir die Benutzeroberfläche oder die Dienstebene erstellen (wir verwenden Jenkins als unser CI-Tool, um den Code zu erstellen, der sich in zwei Git-Repos befindet) und wenn Es gibt Fehler, dann ist etwas in der Serviceschicht kaputt gegangen und das Festschreiben wird nicht akzeptiert.

Wäre es auch eine gute Idee (ist dies eine bewährte Methode?), Dass der Entwickler der Serviceschicht eine Clientbibliothek für den in der UI-Ebene vorhandenen REST-Service erstellt und verwaltet, die bei jeder Änderung aktualisiert wird ihre Service-API? Es ist vorstellbar, dass wir dann den Vorteil einer statisch typisierten API haben, gegen die der UI-Code erstellt. Wenn sich die API der Clientbibliothek ändert, wird der UI-Code nicht kompiliert (sodass wir früher wissen, dass eine wichtige Änderung vorliegt). Ich würde auch weiterhin die Integrationstests beim Erstellen der Benutzeroberfläche oder der Serviceschicht ausführen, um weiter zu überprüfen, ob die Integration zwischen der Benutzeroberfläche und den Diensten noch funktioniert.

rest django

— Empfohlene Vorgehensweise
quelle

6

Wird es Ihnen nicht mitgeteilt, wenn eine API-Änderung vorgenommen wird? In diesen Fällen ist es oft am besten, die API zu versionieren, damit Ihre Benutzeroberfläche immer eine funktionierende Version hat. Dann "aktualisieren" Sie so schnell wie möglich auf die letzte API-Version.

— Matt S

@ MattS: Ich stimme dir zu. Aber mit oder ohne Kommunikation: Ein Upgrade auf eine geänderte API ist viel einfacher, wenn der Compiler Ihnen genau alle Stellen mitteilt, die Sie in Ihrem Code ändern müssen. Obwohl das OP uns immer noch nicht sagt, wie sein Python-Code eine statisch typisierte API bereitstellen wird.

— Doc Brown

1

Wählen Sie im Allgemeinen für Methoden der API, die nicht mehr verfügbar sind, eine Konvention aus und verwerfen Sie sie, insbesondere sobald eine vollständige Ersatz-API verfügbar und getestet ist. Lassen Sie die alte API (im Wesentlichen) an Ort und Stelle, markieren Sie jedoch die Metadaten der Methodensignatur oder fügen Sie ein Protokollierungsereignis ein, damit die Verwendung eindeutig identifiziert werden kann.

Die Protokollierung innerhalb der Service-API ist eine Sache, die Benachrichtigung konsumierender Clients eine andere. Für REST glaube ich nicht, dass es eine solide Standardpraxis gibt. FourSquare-API-Clients können veraltete Methoden erkennen, auch wenn die aufgerufene Methode erfolgreich ist (HTTP 200-Code, jedoch wird errorType auf 'veraltet' gesetzt). Möglicherweise eine vernünftige Strategie, um konsumierenden Kunden die Möglichkeit zu geben, eine veraltete Methode innerhalb der API zu kennen, ohne eine Unterbrechung zu verursachen.

https://developer.foursquare.com/overview/responses

Schlagen Sie in Ihrer API-Anleitung ein Datum oder eine Build-Versionsnummer vor, unter der die veraltete API vollständig entfernt wird. Wenn Sie unsere Strategie für die Ablehnung konkretisieren, möchten Sie die Verbraucher der API über die vorgeschlagene Strategie informieren (wie können sie veraltete Methoden erkennen, wie sie auf die Ersatz-API umsteigen und wann die veraltete API nicht mehr verfügbar ist, wenn während einer API-Bereinigung gelöscht) und Feedback von ihnen einholen, um sicherzustellen, dass der Prozess für alle von Vorteil ist.

— JustinC
quelle

1

Die Versionierung Ihrer API ist eine weitere Möglichkeit. Wenn eine neue Version bereitgestellt wird, lassen Sie auch die alte Version aktiv und erlauben Sie die Aushandlung über die Anforderung. Wenn Sie die neuesten 2 oder 3 Versionen beibehalten, kann der UI-Code in seinem eigenen Tempo aktualisiert werden.

— jiggy
quelle

1

Es gibt mindestens drei Fragen gleichzeitig. Lassen Sie uns diese einzeln beantworten

"Ist es eine gute Idee, eine Client-Bibliothek für den REST-Service zu haben?"

Höchstwahrscheinlich ja, solange Sie keine willkürlichen REST-Aufrufe wünschen, die direkt über Ihren gesamten UI-Code verteilt sind.

"Ist es eine gute Idee, den Entwickler der Serviceschicht die Bibliothek erstellen und verwalten zu lassen?"

Das hängt von den Personen in Ihrem Team ab. Der Betreuer der API sollte sowohl die in der Serviceschicht verfügbaren Dinge als auch die Anforderungen der UI-Schicht kennen. Es kann sich also entweder um eine Person aus der Service-Schicht oder um eine Person aus der UI-Schicht handeln oder (abhängig von der Größe und anderen Aufgaben) um eine Person, die von beiden Teams unabhängig ist.

[Werden wir einen Vorteil daraus ziehen, dass] "Wenn sich die API der Clientbibliothek ändert, wird der UI-Code nicht kompiliert"

Hast du nicht gesagt, dass die Benutzeroberfläche in Python geschrieben wird? Das ist keine statisch typisierte Sprache, daher würde ich keine sofortige Build-Unterbrechung von einer API-Änderung erwarten. Ich gehe davon aus, dass ich Sie an dieser Stelle falsch verstanden habe und Sie hier eine statisch typisierte API haben. Dann können Sie hier einige Vorteile erzielen, solange der Build nicht unterbrochen wird, wenn Sie nur einige neue Funktionen (wie neue optionale Parameter) zur API hinzufügen . Andernfalls verursachen Sie Ihrem Team eine Menge unnötigen Overhead.

— Doc Brown
quelle