Datenumwandlungen: Wer braucht sie überhaupt?

Wie die meisten modernen Webanwendungen interagiert auch die Client-Seite unserer Anwendung mit JSON-Daten. Auch unsere Entwicklungsteams haben in der Vergangenheit hauptsächlich mit JSON gearbeitet. Viele unserer APIs von Drittanbietern hingegen kommunizieren über SOAP-XML-Anfragen, die ganz anders strukturiert sind. Die Aufgabe meines Teams bestand darin, Endpunkte zu erstellen, um diese Integrationsdaten in JSON für unsere internen Entwicklungsteams zugänglich zu machen. Unser Ziel ist es, die Entwicklung so nahtlos wie möglich zu gestalten und dafür zu sorgen, dass sie die Daten so wenig wie möglich in einer anderen Form sehen müssen, als sie es gewohnt sind.
 

Wie sieht das alles aus?

Natürlich müssen wir zunächst herausfinden, wie wir alle benötigten Daten und Informationen von Dritten abrufen können. Außerdem müssen wir erörtern und festlegen, wie diese Informationen über die von uns bearbeitete Anfrage weitergeleitet werden sollen. Wohin gehen die Creds? Was ist mit den Parametern? Was wird in der Anfrage, die wir erhalten, bereitgestellt und wo? Wie soll die Antwort aussehen?

Diese Schritte beinhalten in der Regel die meisten Fragen und das notwendige Hin und Her, um Ideen auszutauschen und Klarheit über ein MVP zu schaffen. Ein oder mehrere Mitglieder sollten dabei sein:

• Lesen der API-Dokumentation
• Versenden von Musteranfragen (z. B. Postman)
• Gespräche mit einem technischen Berater/Entwickler des Drittanbieters, um das Verständnis der API und ihrer Möglichkeiten/Einschränkungen zu überprüfen

Sobald Sie eine erfolgreiche Anfrage erstellt haben, können wir mit den Änderungen und Tests beginnen.

Was soll zurückgegeben werden?

Nachdem Sie nun die API-Antwort gesehen haben, müssen Sie herausfinden, wie Sie sie analysieren, alle einzelnen Datensätze und die gewünschten Felder abrufen oder den Fehlercode und den Kontext abrufen können.

 
In einer idealen Welt sind alle möglichen Zustände/Formen der verschiedenen Antworten/Fehler im Voraus bekannt, und die Daten sind immer vollständig und entsprechen der Dokumentation. Das ist jedoch oft nicht der Fall. In der Regel müssen Sie durch umfangreiche Nachforschungen und Ausprobieren herausfinden, was Ihr Team benötigt, welche Daten möglicherweise nicht verfügbar sind oder welche Daten nur über Umwege zu erhalten sind.

Es ist sehr wichtig, während der ganzen Zeit eine klare Kommunikation zwischen den Teams sowohl über das Produkt(Datenvertrag) als auch über die Erwartungen(Zeitplan und Lieferbarkeit / Qualität und Wartung) aufrechtzuerhalten. Stellen Sie sicher, dass alle Daten, die das Team erwartet, verfügbar sind. Andernfalls stellen Sie die Mittel zur Aggregation dieser Daten bereit, um ein vollständiges Produkt zu liefern.

Nun ist der Code zusammengeführt und freigegeben. Ihr Produkt ist in der freien Wildbahn, und Ihre Daten sind bereit für die Nutzung. Das ist ein guter Zeitpunkt für Ihr Team, um andere über die Nutzung Ihres fantastischen neuen Produkts zu informieren. Einige Ideen sind eine funktionierende Demo des Produkts, vielleicht ein Brown Bag Lunch, um über die Technik oder den Code zu sprechen, und natürlich die gute alte, handliche Dokumentation.

Herausforderungen

Es ist eine Sache, eine erfolgreiche Anfrage zu senden und Daten als Antwort zu erhalten. Zu verstehen, worum es sich bei diesen Daten handelt und wie sich die Parameter der Anfrage im Datensatz widerspiegeln, und dann diese Daten so zu verpacken, dass sie von anderen Teams leichter genutzt werden können (ohne dass diese wissen, wie die ursprünglichen Daten tatsächlich aussahen), ist etwas ganz anderes.

SO VIELE MÖGLICHKEITEN, DAS GLEICHE ZU BEKOMMEN

In einem Fall, in dem wir Anfragen für Buchhaltungssaldodaten getestet haben, haben wir festgestellt, dass der Ausschluss bestimmter Feldzuordnungen dazu führt, dass die Abfrage unter der Haube diese Salden aggregiert und das/die genannte(n) Feld(er) ignoriert. Die Einbeziehung von Abteilungen kann sich beispielsweise nicht auf das Datenvolumen auswirken oder es drastisch erhöhen, je nach Granularität der Abteilungszuordnungen.

SO VIELE ARTEN VON EIN UND DERSELBEN SACHE

Manchmal gibt es sogar bei einem einzelnen Datensatztyp Abweichungen zwischen den einzelnen Datensätzen, die eine differenziertere Parsing-Strategie erfordern. So kann eine API beispielsweise einen einzigen Endpunkt zum Abrufen aller Geschäftsvorgänge bereitstellen. Es gibt jedoch über 40 verschiedene Arten von Transaktionen - jede mit ihrem eigenen, einigermaßen einzigartigen Schema. Diese Transaktionen sind alle in derselben Tabelle gespeichert, und je nach Abfrage können Transaktionen verschiedener Typen in beliebiger Kombination zurückgegeben werden. Ein Teil unserer Entdeckung war es, dies herauszufinden:

• alle gemeinsamen und einzigartigen Eigenschaften bestimmen
• herausfinden, wie sie analysiert werden können
• entscheiden, was in unserem JSON-Schema abgebildet werden soll

SO VIELE NAMEN FÜR EIN UND DIESELBE SACHE

Die Idee, die anderen Teams von diesem Fachwissen Dritter zu trennen, dient den Teams, indem sie ihnen Zeit erspart, etwas Neues lernen zu müssen. Durch die Umgestaltung von Rohdaten wird jedoch auch die Konversation rund um die Daten umgestaltet. Es werden neue Verweise auf Felder mit anderen Namenskonventionen oder abgeleitete Felder erstellt, die in den Rohdaten nicht vorhanden sind. Andere Entwicklungsteams sprechen möglicherweise immer in Bezug auf das JSON-Schema und seine Namenskonventionen - Konventionen, die leicht (oder vollständig) von den API-Daten abweichen können. Beide können auch von der UI-Sprache des Drittanbieters abweichen. Die Ingenieure, die für die Integration verantwortlich sind, müssen das Wissen um diese Parität aufrechterhalten.

Tipps und Hinweise:

Kommunizieren Sie, kommunizieren Sie, kommunizieren Sie! Wie bereits erwähnt, sollten Sie darauf achten, dass der Datenvertrag und die Datenermittlung durchgängig dokumentiert werden. Tauschen Sie Ihr Wissen aus und halten Sie sich gegenseitig über Status, Fortschritte und Hindernisse auf dem Laufenden. So können Sie sicherstellen, dass Ihre Teams auf dem gleichen Weg zum Erfolg sind.

Bei dem Versuch, Daten zu kodieren, könnte es hilfreich sein, eine typisierte Sprache wie TypeScript zu verwenden. Auf diese Weise sind Sie sich immer über die Ausgaben im Klaren und wissen, dass die Daten validiert werden, sobald alles verdrahtet ist. Manche empfinden typisierte Sprachen als umständlich, aber die manuelle Fehlersuche nach unerwarteten fehlerhaften Daten (die sonst gefunden worden wären) kann viel schmerzhafter sein.

Vergessen Sie nicht zu testen!

 
Für Unit-Tests empfehle ich dringend Tests, um sicherzustellen, dass die Strategien für den Aufbau von Anfragen und das Parsen von Antworten so funktionieren, wie Sie es beabsichtigen. Bei Integrationstests kann es sich lohnen, Zeit in die Einrichtung von Tests für die verschiedenen Randfälle von Datenabweichungen zu investieren, um sicherzustellen, dass die für den Verbrauch erwarteten Daten korrekt sind.

In diesem Sinne, lasst uns mit der Verwandlung beginnen, ihr alle!

Calvin Ton

Software-Ingenieur bei FloQast. Musikliebhaber und begeisterter Cratedigger.