APIs und Automatisierung
Dezimalabweichungen in einer API: So untersuchen Sie sie, ohne den Vertrag zu ändern
Ein Beispiel zur Nachverfolgung eines Werts und zwei dokumentierte Fälle helfen dabei, Präzisionsabweichungen einzugrenzen, ohne eine Ursache anzunehmen oder den Vertrag zu ändern.
Was die dokumentierten Fälle zeigen
Eine sichtbare Abweichung bei einem Dezimalwert reicht nicht aus, um daraus zu schließen, dass JSON die Ursache ist oder an welcher Stelle die Abweichung aufgetreten ist. Die verfügbaren Quellen beschreiben zwei konkrete Situationen: Sie sind nützliche Bezugspunkte für eine Untersuchung, legen aber keine allgemeingültige Regel für alle APIs fest.
Esri dokumentierte eine Abweichung bei der Genauigkeit nach dem Dezimaltrennzeichen zwischen Ergebnissen einer ArcGIS-REST-API-Abfrage, die im HTML- und JSON-Format angezeigt wurden. Der Umfang ist im [Esri-Eintrag BUG-000117969](https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969) beschrieben. Der Eintrag belegt, dass diese Abweichung in diesem Fall beobachtet wurde. Er erlaubt jedoch weder, hier ihre Ursache zu bestimmen, noch, sie auf andere Dienste zu übertragen.
IBM dokumentiert, wie sich Fehler bei der Dezimalarithmetik in Db2 for z/OS vermeiden lassen. Der verfügbare Auszug erwähnt die Möglichkeit eines Divisionsfehlers in statischen SQL-Anweisungen sowie die Regel DEC31. Prüfen Sie den Kontext im [IBM-Artikel zu Fehlern bei der Dezimalarithmetik](https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors). Der Artikel ist keine allgemeine Erklärung der Darstellung von Dezimalwerten in JSON.
Trennen Sie bei der Untersuchung daher drei Aspekte: die beobachtete Abweichung, die Stelle im Ablauf, an der Sie sie feststellen, und die Erklärung, die Sie noch überprüfen müssen. So vermeiden Sie, ein konkretes Symptom als Schlussfolgerung über das gesamte System zu behandeln.
- Esri dokumentiert in einem konkreten Fall eine Abweichung zwischen zwei Antwortformaten.
- IBM behandelt ein spezifisches Problem der Dezimalarithmetik in Db2 for z/OS.
- Keiner dieser Fälle legt ein universelles Zahlenformat für andere APIs fest.
Beispiel: Verfolgen Sie dasselbe Feld vom Anfang bis zum Ende
Das folgende Beispiel ist eine Vorlage für die Diagnose, kein veröffentlichtes Testergebnis und keine Empfehlung für ein bestimmtes Format. Angenommen, Sie testen ein Feld namens `betrag` und protokollieren als Eingabe `123.4500`. Bei einem Durchlauf beobachten Sie `123.4500` in der Anfrage, `123.45` an einer Verarbeitungsstelle und `123.45` in der Antwort. Das Beispiel zeigt lediglich, wie eine textuelle Abweichung festgehalten werden kann. Es erlaubt keine Schlussfolgerung dazu, ob sich der interpretierte Wert geändert hat, ob gerundet wurde oder welche Komponente die Beobachtung verursacht hat.
Verfolgen Sie den tatsächlichen Fall, der Ihnen Sorgen bereitet. Notieren Sie den Feldnamen und kopieren Sie die Beobachtungen an jeder zugänglichen Grenze: die von der aufrufenden Seite vorbereiteten Daten, die tatsächlich gesendete Anfrage, die beim Dienst empfangenen Daten, sofern Sie sie beobachten können, alle relevanten Zwischenwerte und die empfangene Antwort. Wenn Sie nur auf Anfrage und Antwort zugreifen können, protokollieren Sie diese beiden Endpunkte und halten Sie fest, dass Sie die internen Schritte nicht beobachten konnten.
Damit das Beispiel reproduzierbar ist, bewahren Sie zusammen mit dem Testbeispiel auch die Schritte auf, mit denen es erzeugt wurde: welcher Vorgang mit welcher Eingabe ausgeführt wurde und welche Antwort zurückkam. Wenn Sie zwei Durchläufe vergleichen, ändern Sie jeweils nur eine relevante Bedingung und protokollieren Sie, welche es war. Ändern Sie nicht gleichzeitig den Wert, den Vorgang und die Darstellung, da sonst schwerer zu erkennen ist, welche Abweichung Sie vergleichen.
Vergleichen Sie die erfassten Beispiele, nicht nur eine Bildschirmansicht oder einen Bericht, der die Daten möglicherweise anders darstellt. Tritt die Abweichung nur in einer Ansicht auf, halten Sie das genau so fest und versuchen Sie, auch die zugehörige Anfrage oder Antwort zu erfassen. Protokollieren Sie die erste Stelle, an der Sie die Abweichung beobachten können. Das ist ein praktischer Befund, aber kein automatischer Beweis für die interne Ursache.
- Feld: `betrag`. Beobachtete Eingabe: `123.4500`.
- Verarbeitung: Protokollieren Sie den beobachteten Wert oder geben Sie an, dass dieser Schritt nicht einsehbar ist.
- Ausgabe: Kopieren Sie die empfangene Antwort und halten Sie fest, ob die Abweichung bereits zuvor vorlag.
- Kennzeichnen Sie den Fall als veranschaulichend, wenn Sie für einen Test erfundene Werte verwenden.
So bereiten Sie eine aussagekräftige Prüfung vor
Legen Sie vor dem Test fest, was Sie herausfinden möchten. Zum Beispiel: „An welcher Stelle dieses Ablaufs tritt die Abweichung zwischen dem gesendeten und dem empfangenen Wert zum ersten Mal auf?“ Das ist eine besser überprüfbare Frage als „Warum verändert JSON die Dezimalstellen?“, denn diese Frage setzt eine bislang nicht belegte Ursache voraus.
Verwenden Sie ein kleines Testbeispiel, das den Fall reproduziert, und behalten Sie bei den Vergleichen dieselbe Eingabe bei. Bestimmen Sie den betroffenen Endpunkt und Vorgang und notieren Sie, ob die Antwort aus demselben Durchlauf oder einem anderen Test stammt. Tritt das Problem nur bei einem bestimmten Vorgang auf, halten Sie diese Bedingung fest, statt das Verhalten als allgemeingültig darzustellen.
Vergleichen Sie anschließend jede Beobachtung mit der vorherigen: vorbereitete Anfrage mit tatsächlich gesendeter Anfrage, gesendete Anfrage mit empfangener Antwort und – sofern möglich – Ein- und Ausgabedaten des untersuchten Verarbeitungsschritts. Wenn Sie auf einen Schritt keinen Zugriff haben, füllen Sie die Lücke nicht mit einer Annahme. Schreiben Sie „nicht beobachtet“ und fahren Sie mit den Grenzen fort, die Sie überprüfen können.
Eine Wiederholung mit denselben Schritten kann dabei helfen zu dokumentieren, ob Sie die Abweichung unter diesen Bedingungen erneut beobachten. Ändert sich das Ergebnis, halten Sie auch das fest. Keines der beiden Ergebnisse identifiziert für sich allein eine Ursache: Sie dienen dazu, den Fall zu beschreiben und die nächste Prüfung zu formulieren.
- Formulieren Sie vor dem Test eine konkrete Frage.
- Behalten Sie das Testbeispiel unverändert bei und protokollieren Sie jede geänderte Bedingung.
- Unterscheiden Sie zwischen beobachteten Daten, nicht zugänglichen Schritten und noch offenen Hypothesen.
- Halten Sie genügend Schritte fest, damit eine andere Person den Fall wiederholen kann.
Befunde einordnen, ohne den Vertrag zu ändern
Ein solcher Test kann zeigen, dass zwei Beobachtungen voneinander abweichen, und eingrenzen, an welcher Stelle die Abweichung festgestellt wird. Er belegt für sich allein nicht, welcher interne Vorgang sie verursacht hat. Zu den möglichen Untersuchungsbereichen zählen Unterschiede im gesendeten Testbeispiel, in einem beobachteten Verarbeitungsschritt oder in der Darstellung des Ergebnisses. Behandeln Sie diese als Möglichkeiten, die überprüft werden müssen, nicht als bestätigte Erklärungen.
Wandeln Sie das Feld nicht in eine Zeichenfolge um, ändern Sie nicht seine Skalierung und runden Sie nicht vorsorglich, ohne zuvor den geltenden Vertrag zu prüfen. Die verfügbaren Belege stützen weder eine allgemeine Empfehlung für Zahlen, Zeichenfolgen oder kleinere Einheiten noch eine universelle Regel für Skalierung oder Rundung. Eine Änderung der Darstellung könnte die Interpretation des Felds gemäß dem Vertrag verändern. Klären Sie zuerst, was dieser zulässt und was das Feld bedeutet.
Wenn die Dokumentation des Endpunkts die Darstellung oder das erwartete Ergebnis nicht erläutert, stellen Sie dem Dienstverantwortlichen diese Frage anhand des reproduzierbaren Falls. Bitten Sie um eine konkrete Antwort für das betreffende Feld, den Vorgang und den Endpunkt. Eine klare Definition ermöglicht die Entscheidung, was zu vergleichen ist. Fehlt eine Definition, lässt sich daraus keine Regel für andere Dienste ableiten.
- Behandeln Sie die erste Stelle, an der Sie die Abweichung sehen, als Beobachtungsgrenze, nicht als bestätigte Ursache.
- Prüfen Sie den Vertrag, bevor Sie Typ, Skalierung oder Rundung ändern.
- Stellen Sie dem Anbieter die offene Frage konkret und anhand eines reproduzierbaren Falls.
Den Fall und seine Grenzen weitergeben
Wenn Sie um Hilfe bitten, teilen Sie ein minimales Testbeispiel, das die Abweichung belegt, sowie die zu ihrer Reproduktion nötigen Schritte. Geben Sie an, welchen Wert Sie erwartet haben, was Sie beobachtet haben und in welchen Schritten Sie messen konnten. War ein Schritt nicht einsehbar, sagen Sie das ausdrücklich. So kann die prüfende Person Eingabedaten, Ergebnis und noch offene Fragen voneinander unterscheiden.
Entfernen Sie vor dem Speichern oder Weitergeben von Protokollen Zugangsdaten sowie nicht erforderliche personenbezogene oder sensible Daten. Beschränken Sie den Zugriff auf die Beispiele und legen Sie fest, wie lange sie aufbewahrt werden, entsprechend den Anforderungen der Untersuchung.
Halten Sie Ihre Schlussfolgerung schließlich im Verhältnis zu den Belegen: Sie können über eine reproduzierbare Abweichung in einer konkreten Integration berichten und beschreiben, wo Sie sie festgestellt haben. Übertragen Sie das Ergebnis nicht auf Werte, Vorgänge oder Dienste, die Sie nicht getestet haben. Die Fälle von Esri und Db2 sind nützliche dokumentierte Bezugspunkte, ersetzen aber nicht die Festlegung des erwarteten Verhaltens Ihrer API.
- Fügen Sie das minimale Testbeispiel, die Schritte und die beobachtete Antwort bei.
- Trennen Sie reproduzierbare Ergebnisse von noch offenen Hypothesen.
- Schwärzen Sie sensible Informationen und beschränken Sie den Zugriff auf die Protokolle.
Häufige Fragen
Beweist eine Dezimalabweichung in der Antwort, dass JSON die Ursache ist?
Nein. Esri dokumentiert in einem Fall der ArcGIS REST API eine Abweichung bei der Genauigkeit zwischen HTML- und JSON-Ergebnissen. Dieser Fall belegt jedoch keine allgemeingültige Ursache für andere APIs.
Sollte ich Dezimalwerte immer als Zeichenfolgen senden?
Die hier verfügbaren Belege stützen keine allgemeine Empfehlung für ein bestimmtes Format. Prüfen Sie im Vertrag des Endpunkts, welche Darstellung zulässig ist und wie das Feld interpretiert werden soll.
Welche Schlussfolgerung erlaubt das Beispiel zur Nachverfolgung?
Es ermöglicht, Beobachtungen in verschiedenen Schritten festzuhalten und anzugeben, wo Sie eine Abweichung zum ersten Mal festgestellt haben. Für sich allein belegt es nicht die interne Ursache.
Welche Informationen sollte ich dem Anbieter schicken?
Ein minimales, bereinigtes Testbeispiel, die Schritte zu seiner Reproduktion, die beobachtete Abweichung und die Schritte, die Sie überprüfen konnten. Geben Sie außerdem an, welches erwartete Verhalten noch geklärt werden muss.
Quellen und weitere Informationen
Für diesen Artikel herangezogene Dokumentation.
- Cómo evitar errores de aritmética decimal - Db2 — IBM
- BUG-000117969 for ArcGIS GIS Server — Esri Support
Apification entdecken
Ähnliche Artikel
APIs und Automatisierung
Webhooks oder Polling zur Erkennung von Dateiänderungen: So treffen Sie die Wahl
Vergleichen Sie Benachrichtigungen und regelmäßige Abfragen, um eine Strategie zur Erkennung von Änderungen zu wählen, die zu Ihrer gewünschten Latenz, dem Änderungsvolumen und Ihren Anforderungen an die Wiederherstellung passt.
APIs und Automatisierung
Webhooks in falscher Reihenfolge: So verhindern Sie, dass ein altes Ereignis den Dateistatus zurücksetzt
Der Empfangszeitpunkt beweist nicht, welche Änderung zuerst erfolgt ist. Erfahren Sie, wie Sie den Webhook-Vertrag prüfen und den Dateistatus anhand überprüfbarer Kriterien abgleichen.
APIs und Automatisierung
Dateien in einer API identifizieren – ohne sich auf veränderliche Namen oder Pfade zu verlassen
Entwirf Referenzen, die weniger von Umbenennungen und Verschiebungen abhängen: Prüfe den OpenAPI-Vertrag, speichere Zuordnungen und teste mögliche Synchronisierungsfehler.