Nach dem tatsächlichen Start des Projekts stieß der Autor jedoch auf einige schwerwiegende Probleme :
1. Fehlen einer vollständigen API-Dokumentation und -Spezifikationen :
· Die API-Dokumentation ist unvollständig und voller Fehler und kann nicht als genaue Referenz verwendet werden.
· Es gibt keinen vereinbarten API-Testprozess, sodass das Backend-Entwicklungsteam die API nach Belieben und ohne Vorankündigung ändern und veröffentlichen kann. Bei solchen Änderungen handelt es sich häufig um Fehler, die die Integration mit API-Clients unterbrechen.
2. Unangemessenes API-Framework und Validierung :
Das Backend- Team verwendete ein ungeeignetes Flask-Framework und implementierte selbst eine komplexe Nutzlastvalidierung, von der die meisten nicht getestet wurden.
· Der Überprüfungsteil enthält eine große Menge Code, einschließlich der Überprüfung von Datum, Zeitstempel und Zeichenfolgenformat, wurde jedoch nicht vollständig getestet, was den Projektfortschritt erheblich verlangsamt.
Um die oben genannten Probleme zu lösen , ist es daher erforderlich, die API-Dokumentation zu reparieren und zu verbessern, um deren Genauigkeit und Vollständigkeit sicherzustellen . Außerdem müssen strenge API-Spezifikationen festgelegt werden, um die Veröffentlichung solcher Versionen zu verhindern nicht den Spezifikationen entsprechen.
API-Design und Dokumentation korrigieren
Anhand der oben dargelegten Probleme lässt sich erkennen, dass das Entwicklungsteam die Best Practices der REST-API und der OpenAPI-Spezifikation nicht versteht. Daher muss das Entwicklungsteam zunächst OpenAPI und seine Funktionsweise verstehen und die API-Dokumentation in die OpenAPI-Spezifikation integrieren, um ein klareres Verständnis des erwarteten Verhaltens der API zu erhalten.
Bei der Integration der Dokumentation in die OpenAPI-Spezifikation haben wir viele Probleme mit früheren API-Designs entdeckt. Beispielsweise erforderten benutzerdefinierte Datumsformate bisher eine benutzerdefinierte Validierungslogik auf dem Server und in der Benutzeroberfläche. Wir haben dieses Problem gelöst, indem wir zur Darstellung von Datumsangaben auf den von OpenAPI unterstützten ISO-Standard umgestiegen sind.
Darüber hinaus sind einige Modi so flexibel, dass die Validierung nahezu wirkungslos ist. Um die Validierung zu verbessern, haben wir die Schemata umgestaltet und ein Modell mit unterschiedlichen Endpunkten für jede Entität erstellt, um es benutzerfreundlicher zu machen.
HTTP-Methoden und Statuscodes wurden im vorherigen Design unangemessen verwendet. Das Team verwendet nur GET- und POST-Methoden und alle Antworten geben einen Statuscode 200 zurück. Diese unsachgemäße Verwendung macht es unklar, wenn versucht wird, Ressourcen zu erstellen, zu löschen oder zu aktualisieren. Um dieses Problem zu lösen, haben wir die Verwendung von HTTP-Methoden neu definiert und geben den entsprechenden Statuscode korrekt zurück, um den Erfolg oder Misserfolg der Anfrage genauer anzuzeigen.
Eine weitere Einschränkung des vorherigen Designs war die „Wiederverwendung von Endpunkten“. Obwohl es den Anschein erweckt, Code zu sparen, werden tatsächlich zu viele Implementierungsdetails offengelegt. Daher müssen wir das Konzept betonen, zuerst die API zu entwerfen und dann über die Implementierung nachzudenken.
Die Zusammenführung der API-Spezifikation mit OpenAPI war ein wichtiger Wendepunkt für das Projekt. Danach konnten wir einen Scheinserver ausführen, um die Benutzeroberfläche vor der Integration in das Backend zu erstellen und zu testen und die Backend-Implementierung anhand der Spezifikation zu überprüfen. Wir verwenden Prism, um den Mock-Server auszuführen, und Dredd, um die Serverimplementierung zu überprüfen (obwohl ich jetzt lieber Schemathesis verwende). Dadurch können Projekte klarer und effizienter ablaufen .
API-Release-Prozess korrigieren
Selbst wenn ein API-Dokument vorhanden ist und es vor der Veröffentlichung nicht anhand der API-Spezifikation getestet wird, wird die Rolle des Dokuments eingeschränkt. Während die Dokumentation selbst uns hilft, die Funktionsweise der API zu verstehen, liegt ihre wahre Stärke in ihrer Funktion als Verifizierungstool – das überprüft, ob der Server korrekt implementiert ist.
Um sicherzustellen, dass der API-Server wie erwartet läuft, habe ich die Dredd-Testsuite in den Continuous-Integration-Server integriert. Niemand kann neuen Code zusammenführen und veröffentlichen, es sei denn, er besteht die Dredd-Validierung und entspricht der API-Spezifikation. Dieser Schritt ermöglicht es dem Team, versehentliche Änderungen am API-Server zu vermeiden. Von nun an müssen alle Änderungen am Server im Voraus dokumentiert werden, und es muss sichergestellt werden, dass der API-Server diese Änderungen vor der Zusammenführung oder Veröffentlichung befolgt. Dieser Ansatz gewährleistet die Stabilität und Konsistenz des Servers.
Wählen Sie das richtige API-Entwicklungsframework
Zuvor implementierte das Team den API-Server mithilfe des Flask-Frameworks, einem beliebten Python-Framework zum Erstellen von Webanwendungen. Sie haben die API mit dem einfachen Flask erstellt und viel benutzerdefinierten Code geschrieben, um die API-Nutzlast zu validieren. Dies ist ein häufiger Fehler, den viele unerfahrene API-Entwickler machen.
Der Aufbau einer benutzerdefinierten API-Validierungsschicht ist nicht unerwünscht, aber ein übermäßiges Vertrauen in diesen Ansatz kann dazu führen, dass das Rad neu erfunden wird. Die API erfordert eine komplexe Validierungslogik zur Verarbeitung der Nutzlast und der URL (Pfad und Abfrageparameter), die in der gesamten API implementiert werden muss. Wenn Sie also darauf bestehen, Ihre eigene API-Verifizierungsschicht zu erstellen, werden Sie letztendlich ein API-Framework erstellen. Es stehen jedoch viele hervorragende API-Entwicklungs-Frameworks zur Verfügung. Warum also nicht eines davon auswählen?
Speziell für Flask gibt es mehrere Optionen, die in Betracht gezogen werden sollten. Aber nicht alle Frameworks sind gleich. Zum Beispiel flasgger, restx (Nachfolger von flask-restplus), flask-RESTful und flask-smorest usw. Wie trifft man bei so vielen Möglichkeiten eine Entscheidung?
Bei der Auswahl eines REST-API-Entwicklungsframeworks sollten die folgenden Faktoren berücksichtigt werden:
· OpenAPI-Unterstützung : Das Framework sollte die einfache Erstellung von REST-APIs ermöglichen und automatisch eine API-Dokumentation generieren, um die Korrektheit der Nutzlastüberprüfung sicherzustellen. Zu den Referenzframeworks gehören Flasgger und flask-smorest.
· Robuste Datenvalidierung : Die Validierung von Nutzlasten erfordert eine robuste Datenvalidierungsbibliothek, um verschiedene Attribute und Typen zu verarbeiten. Die Bibliothek sollte optionale und erforderliche Eigenschaften wie Zeichenfolgenformate (ISO-Datum und UUID) sowie eine strikte und lockere Typvalidierung unterstützen. Im Python-Ökosystem sind Pydantic und Marshmallow hervorragende Datenvalidierungsbibliotheken, und Flasgger und Flask-Smorest können Marshmallow verwenden.
Umfassende Validierung : Das Framework sollte die Validierung von Anforderungsnutzlasten, Antwortnutzlasten, URL-Pfadparametern und URL-Abfrageparametern unterstützen. Einige Bibliotheken validieren möglicherweise nur die Anforderungsnutzlast und ignorieren URL-Parameter oder Antwortnutzlast. Stellen Sie sicher, dass das Framework mindestens eine Möglichkeit zur Durchsetzung von Validierungsregeln bietet. Bei Verwendung von Marshmallow kann die Antwortnutzlast direkt anhand ihres Modells überprüft werden.
· Reife : Wählen Sie eine Bibliothek, die ausgereift und stabil ist und aktive Community-Unterstützung bietet. Es sollte über eine gute Dokumentation verfügen und in der Lage sein, Benutzerprobleme schnell zu lösen.
Nach der Bewertung der oben genannten Faktoren haben wir uns für flask-smorest entschieden, ein Flask-Plug-in, das die Verwendung von Marshmallow unterstützt, um auf einfache Weise eine Datenüberprüfung für REST-APIs zu erstellen. Es kann den Datenüberprüfungsprozess vereinfachen und die Menge an benutzerdefiniertem Code reduzieren. Sowohl Anforderungs- als auch Antwortnutzlasten werden jetzt ordnungsgemäß validiert, und Marshmallow übernimmt auch die Validierung von URL-Abfragen und Pfadparametern.
Die Wahl des richtigen API-Frameworks ermöglicht uns eine funktionierende API. Da das Framework die Details der API-Schicht verwaltet, können wir uns stärker auf die Geschäftslogik und das Datenmodell der Anwendung konzentrieren, was zu einer höheren Entwicklungsgeschwindigkeit und der Möglichkeit führt, bessere Software häufiger zu veröffentlichen.
Berücksichtigen Sie alles, um eine großartige API zu erstellen
Im heutigen Internet sind APIs überall und unvermeidlich. Allerdings ist die Erstellung einer wirklich guten API eine komplexe Aufgabe. Genauso wie das Schreiben von Code, der lesbar und leicht zu warten ist, ist auch die Erstellung einer hochwertigen, benutzerfreundlichen und leicht zu ändernden Schnittstelle eine Herausforderung bei der API-Entwicklung.
Die Bereitstellung einer qualitativ hochwertigen API ist schwierig, da sie den Geschäftsanforderungen entsprechen muss, d. h. Client und Server müssen dieselben Konventionen und Spezifikationen verwenden, da sonst die Integration schwierig zu erreichen ist.
Um dieses Ziel zu erreichen, müssen mehrere Aspekte berücksichtigt werden: Kundenanforderungen erfassen, Anforderungen in technische Details übersetzen, API entwerfen, Dokumentation schreiben, ein geeignetes API-Framework auswählen und korrekt verwenden, API testen und sicherstellen, dass die Implementierung den Designspezifikationen entspricht. Aspekte wie API-Sicherheit, Bereitstellung und Betrieb sind hiervon nicht umfasst.
Wenn es um die Entwicklung geschäftskritischer APIs geht, empfiehlt es sich, diese Aufgabe nicht allein den Nachwuchsentwicklern zu überlassen. Sie können teilnehmen, es wird jedoch ein leitender Entwickler benötigt, der ihre Arbeit leitet. Wenn Sie keine Erfahrung in der API-Entwicklung haben, folgen Sie dem Best-Practice-Pfad: Entwerfen Sie zuerst die API, schreiben Sie dann die Dokumentation, implementieren Sie sie gemäß der Spezifikation und überprüfen Sie sie. Erfinden Sie das Rad nicht neu, wählen Sie das richtige Framework!
Obwohl es einige Zeit dauern kann, OpenAPI zu erlernen, das API-Test-Framework zu verstehen, das API-Entwicklungs-Framework zu erforschen usw., lohnt es sich. Wenn nicht, geraten Sie in einen Teufelskreis aus API-Integration und Softwarequalitätsproblemen, der den Projektfortschritt behindert und enorme Kosten für die Behebung von Problemen verursacht.
Wenn Sie über ausreichende Ressourcen und erfahrene API-Entwickler verfügen, erhöht sich die Wahrscheinlichkeit, die API korrekt zu erstellen, erheblich und Sie können viel Geld sparen. Darüber hinaus müssen wir auch auf das Management von APIs achten. Viele Probleme liegen nicht nur in den frühen Entwicklungs- und Aufwandskosten, sondern auch in versteckten Codeproblemen während des Entwicklungsprozesses und unklaren Übergaben verantwortlicher Mitarbeiter, die versteckte Gefahren verursachen können. Daher ist Power Simple Integration davon überzeugt, dass das API-Management Tools von Drittanbietern verwenden kann, um APIs aus einer Hand zu verwalten, wobei mehrere Rollen beteiligt sind, um Verantwortungsverluste zu vermeiden und die Entwicklungseffizienz zu verbessern.
Ursprünglicher Link : Schnellere Markteinführungszeit | von Jose Haro Peralta |