Hier ist, wie es in den letzten Jahren aussah:
- im Jahr 2014 an Backbone.js,
- in den Jahren 2015-16 an AngularJS,
- im Jahr 2017 an Angular 2/4,
- im Jahr 2018 an React.js,
- Was wird als nächstes passieren? Vue.js?
sowie an einigen Back-Ends (Java, Python, CF, Node.js etc.), die REST-API-Endpunkte bereitstellen.
Dieses Setup verschiebt eine Vielzahl von Daten, Abruf und Verarbeitungscode vom Back-End “BE” (Webserver) zum Front-End “FE” (Webbrowser, mobile App). Es erleichtert die Entwicklung am Back-End, erhöht aber die Komplexität am Front-End enorm. Hinzu kommt, dass es eine Reihe neuer Probleme mit der API-Kompatibilität gibt.
Vorteile der Umstellung auf die REST-API
In der Theorie sollte die REST-API nur Vorteile haben, die Folgendes beinhalten:
- viel bessere, reaktionsschnelle Benutzeroberfläche,
- Verschieben der HTML-Generierung von BE nach FE, wo sie einfach und schnell aktualisiert werden kann,
- Systementkopplung,
- Ermöglichung der unabhängigen Entwicklung von FE und BE (zumindest in der Theorie).
Problem
Real life vs REST API
Aber in der Praxis (und Praxis schlägt immer die Theorie in der IT) verursacht sie für die meisten Entwicklerteams vor allem große Probleme mit der Dateninkompatibilität auf REST-API-Endpunkten.
Diese Probleme verschärfen sich mit mehreren Back-End-Schritten (z.B. Microservices) BE->BE->FE und umgekehrt beim Schreiben von Daten FE<-BE<-BE, was zu unnötigen Stunden für alle Entwickler und zu Frustration von Kunden/Produktinhabern führt.
Noch schlimmer ist, dass API-Teile von Teams in einem anderen Büro/Land entwickelt wurden – Stunden werden zu Tagen und Wochen verschwendet.
Diese Unterschiede ergeben sich aus realen Situationen wie z.B:
- ein anderer Entwickler hat den API-Endpunkt geändert (FE oder BE, aber nicht beides),
- FE und BE wurden nicht zur gleichen Zeit (und ohne API-Versionierung) bereitgestellt,
- ein Tippfehler im API-Aufruf, der schwer zu debuggen ist,
- Fehlerstatuscode und fehlende Debug-Informationen an einem API-Endpunkt.
Lösung
Verwendung einer KonstruktionsrichtlinieIm
Allgemeinen hilft es, wenn Sie einige REST-API-Designrichtlinien befolgen (z.B. dies oder das). Aber es wird nicht alle der oben genannten Probleme vollständig lösen. Normalerweise können wir nicht alle Teile der API in großen Systemen kontrollieren. So bleibt Ihr Leitfaden „auf dem Papier“ und hat in der Praxis keine Bedeutung. Außerdem gibt es keine automatische Möglichkeit, zu überprüfen, ob die API den gewählten Richtlinien entspricht, da es sich nur um Artikel in menschlicher Sprache handelt. Neben der Einhaltung einer Richtlinie müssen sich Ihre API-Endpunkte auf beiden Seiten einigen.
Verwendung von automatisch generierter Dokumentation und Tests
Wir brauchen etwas, auf das wir uns verlassen können – eine Dokumentation, die sich selbst automatisch testet und das Problem sofort und automatisch verfolgt, im Gegensatz zu einer manuellen.
Manuell geschriebene Dokumentationen werden schnell überflüssig und sind daher irreführend und schädigen den Entwickler-Workflow. Infolgedessen lesen die meisten Entwickler es nicht und vertrauen ihm auch nicht.
Manuelle API-Tests müssen hunderte Male wiederholt werden. Sie sind auch schwierig und zeitaufwendig (z.B. Einstellen und Verwalten von Daten in POSTman). In den meisten IT-Projekten ist es jedoch nach wie vor üblich, dies zu tun. Glücklicherweise ist die Automatisierung beider Verfahren recht einfach zu realisieren.
Tools verwenden
Schritt 1 – Automatische Generierung der Dokumentation
Die meisten Entwickler sind vertraut mit REST-API-Tools zur Beschreibung und Dokumentation von REST-API-Endpunkten wie:
Für einen Vergleich klicken Sie bitte hier.
Beide enthalten viele nützliche Tools und Integrationen:
Auch die Generierung des Swagger-Definitionsformats (das einen API-Endpunkt auf der Serverseite detailliert beschreibt) mit der Swagger-Oberflächenansicht aus dem Quellcode wird immer häufiger (z.B. Hapi.js mit Swagger-Plugin oder JAX-RS mit Annotationen).
Es garantiert aber immer noch nicht, dass die Dokumentation vollständig mit dem Verhalten des Codes übereinstimmt. In komplexen Systemen haben Sie weder die Kontrolle über alle API-Endpunkte, noch können Sie diese ändern oder automatisch Dokumente generieren lassen.
Schritt 2 – Automatische API-Tests
Wenn Sie Glück haben und alle Endpunkte vollständig dokumentiert und mit Swagger oder RAML beschrieben sind, können Sie mit Hilfe von Tools mit geringem Aufwand automatisch eine API erstellen und ausführen:
- für Swagger (https://swagger.io/commercial-tools/),
- für RAML (https://raml.org/projects), e.g. Abao.
Es wird ein großer Vorteil für die tägliche Entwicklung sein.
Aber zurück zur Realität – das kann nur in kleinen Projekten passieren. Normalerweise haben Sie diesen Komfort nicht, und Sie müssen selbst automatische API-Tests schreiben.
Dafür empfehle ich Frisby.js. API-Tests sind sehr einfach zu schreiben und erfordern wenig Code. Sie laufen in Sekundenschnelle und können für den automatischen Betrieb eingerichtet werden.
Zusammenfassung
Das größte Problem mit der REST-API ist die Einigung über die Endpunkte. Das führt zu Mehraufwand und dauert länger, und die Frage der Inkompatibilität muss immer berücksichtigt werden. Zumindest werden Sie gezwungen sein, den Teil des Systems zu identifizieren, der die Probleme verursacht, dann zu erraten, wer das Problem beheben sollte, und es ihnen zuzuweisen, natürlich in der Hoffnung, dass es nicht immer wieder neu zugewiesen wird. Es ist Zeitverschwendung.
Eine schnelle Auflistung der REST-API-Bugs und deren Zuordnung zum verantwortlichen Entwickler ist der Schlüssel zu einem erfolgreichen „modernen Web“-Projekt. Die in diesem Artikel genannten Werkzeuge sind nur Beispiele. Finden und nutzen Sie die Tools, die am besten zu Ihrem Workflow passen.
Full Stack, JavaScript und Webentwickler bei JCommerce mit 15 Jahren Erfahrung in allen Bereichen der Entwicklung von Webanwendungen. In den letzten Jahren verantwortlich für die Migration der Legacy-Codebasis auf moderne Web-Technologien in einer Reihe von Projekten.