API-Paginierung: So durchlaufen Sie eine Sammlung

Was es bedeutet, eine paginierte Sammlung zu erhalten

Eine paginierte Sammlung liefert ihre Ergebnisse in mehreren Teilen, statt sie alle in einer einzigen Antwort zurückzugeben. Für die Integration wird aus einem scheinbar einfachen Lesevorgang so ein Ablauf: Sie müssen einen Teil anfordern, ihn verarbeiten und anhand der Regeln des Endpoints feststellen, ob ein weiterer Teil angefordert werden soll. Sensedia empfiehlt, Paginierung bei Diensten zu verwenden, die große Datenmengen zurückgeben. Das ist eine Empfehlung dieser Quelle und keine Regel, die das Verhalten jeder API beschreibt. Quelle: https://www.sensedia.com.es/post/api-buenas-practicas-de-paginacion-y-filtros.

Der konkrete Mechanismus kann unterschiedlich sein. In der Dokumentation des Dienstes können ein Fortsetzungssignal, ein Parameter oder eine andere Möglichkeit beschrieben sein, mit der angezeigt wird, wie es weitergeht. Wählen Sie nicht aus Gewohnheit eine dieser Möglichkeiten. Identifizieren Sie vor der Implementierung drei Elemente im geltenden Vertrag: wie der Lesevorgang beginnt, welche Information eine Fortsetzung ermöglicht und welche Bedingung das Ende kennzeichnet. Fehlt eines davon, klären Sie diesen Punkt, bevor Sie eine Antwort als vollständige Sammlung behandeln.

Es empfiehlt sich, zwei Fragen auseinanderzuhalten, die oft verwechselt werden: „Habe ich eine korrekte Antwort erhalten?“ und „Habe ich die gesamte Sammlung durchlaufen?“. Die erste Frage bezieht sich auf den gerade ausgeführten Aufruf. Für die zweite müssen Sie das für diesen Vorgang beschriebene Verfahren befolgen und dessen Abschlussbedingung erreichen.

• Prüfen Sie das Verhalten des konkreten Endpoints; leiten Sie den Mechanismus nicht aus dem Namen der API ab.
• Suchen Sie sowohl nach dem Fortsetzungssignal als auch nach der dokumentierten Bedingung, bei der der Durchlauf endet.
• Behandeln Sie die Aussage von Sensedia als Empfehlung und nicht als Garantie für einen bestimmten Dienst.

Ein praktisches, vom Vertrag abhängiges Verfahren

Sie können die Implementierung als konzeptionelle Schleife strukturieren. Dieses Schema schreibt weder Parameternamen noch eine allgemeingültige Antwortstruktur vor: Ersetzen Sie jedes Element durch die Vorgaben in der technischen Dokumentation des Endpoints.

1. Legen Sie den abzufragenden Vorgang fest und notieren Sie Methode, Endpoint und erforderliche Anfangsparameter. 2. Senden Sie die erste Anfrage und verarbeiten Sie die Ergebnismenge aus dieser Antwort. 3. Prüfen Sie die vom Dienst beschriebene Fortsetzungsinformation. 4. Zeigt diese Information an, dass es einen weiteren Teil gibt, bereiten Sie die nächste Anfrage genau nach den Vorgaben des Vertrags vor und verarbeiten Sie erneut deren Ergebnisse. 5. Beenden Sie die Schleife erst, wenn die vom Dienst dokumentierte Abschlussbedingung erfüllt ist.

Als Pseudocode lautet die Idee: „Gemäß Vertrag starten; solange der Vertrag eine Fortsetzung anzeigt, den nächsten Teil über den dokumentierten Mechanismus anfordern und seine Ergebnisse verarbeiten; anhalten, sobald das dokumentierte Signal das Ende anzeigt.“ Dieser Pseudocode ist bewusst abstrakt und keine Anleitung für eine bestimmte API. Erstellen Sie nicht eigenständig eine URL, Seitennummer oder einen Cursor, wenn der Vertrag nicht vorgibt, dass Sie dies tun sollen.

Notieren Sie vor der Implementierung der Schleife, welches konkrete Antwortdatum als Fortsetzung interpretiert wird und welcher Wert oder Status das Ende markiert. Ermitteln Sie auch, was – sofern vom Dienst vorgegeben – zwischen den Anfragen gespeichert werden muss. Diese kurze Beschreibung erleichtert anderen die Überprüfung des Ablaufs und hilft, Interpretationsfehler zu erkennen, ohne dem Anbieter unveröffentlichte Regeln zuzuschreiben.

• Start: Verwenden Sie die Anfangsparameter, die für den Vorgang dokumentiert sind.
• Fortsetzung: Verwenden Sie ausschließlich das für diesen Endpoint beschriebene Signal und Verfahren.
• Abschluss: Beenden Sie den Durchlauf, sobald die veröffentlichte Bedingung erfüllt ist. Es reicht nicht, dass eine einzelne Antwort nur wenige Ergebnisse zu enthalten scheint.
• Definiert die Dokumentation einen Schritt nicht, halten Sie die offene Frage fest und bitten Sie um Klärung, statt eine Regel zu erfinden.

Ein konkretes Beispiel: New Relic REST API v2

Die Dokumentation der New Relic REST API v2 gibt an, dass die Antwort bei paginierten Daten einen Link-Header enthält, der die Anzahl der Seiten und die gerade abgefragte Seite angibt. Dies ist ein konkretes Beispiel für Informationen, die ein Anbieter für seine API dokumentiert. Es belegt nicht, dass andere Dienste denselben Header enthalten, und lässt sich nicht ohne Weiteres auf einen anderen Endpoint übertragen. Dokumentation: https://docs.newrelic.com/es/docs/apis/rest-api-v2/basic-functions/pagination-api-output/.

Notieren Sie beim Prüfen dieser Referenz, was sie über den Header aussagt, und vergleichen Sie es mit dem Vorgang, den Sie tatsächlich verwenden möchten. Die beschriebene Information nennt die Gesamtzahl der Seiten und die abgefragte Seite. Gehen Sie nicht allein aufgrund dieser Angaben davon aus, wie die nächste Anfrage erstellt werden muss: Befolgen Sie für diesen Vorgang die geltenden Anweisungen in der New-Relic-Dokumentation.

Das Beispiel zeigt auch, warum es hilfreich ist, zwischen „einem möglichen Muster“ und „dem Vertrag meines Endpoints“ zu unterscheiden. Verwendet ein Anbieter ein anderes Signal oder definiert er andere Bedingungen, muss der Ablauf Ihrer Integration entsprechend angepasst werden. Das Beispiel dient als Orientierung beim Lesen der Dokumentation, nicht als universelle Vorlage.

• Der in der Quelle beschriebene Link-Header bezieht sich auf die New Relic REST API v2.
• Prüfen Sie in der geltenden Dokumentation, wie der Durchlauf fortgesetzt wird. Leiten Sie aus einer einzelnen Angabe keine zusätzlichen Anweisungen ab.

Was Sie prüfen sollten, wenn der Lesevorgang unterbrochen wird oder Datensätze doppelt auftreten

Stellen Sie sich vor, der Prozess wird angehalten, nachdem einige Teile empfangen wurden, aber bevor die Abschlussbedingung erreicht ist. Markieren Sie den Import nicht allein deshalb als abgeschlossen, weil bereits Ergebnisse gespeichert wurden. Halten Sie fest, dass der Durchlauf unterbrochen wurde, und prüfen Sie vor der Wiederaufnahme, was der Vertrag zur Fortsetzung zulässt. Sie können nicht davon ausgehen, dass eine Position oder ein Cursor unbegrenzt erhalten bleibt oder wiederhergestellt werden kann.

Die Wiederaufnahme ist eine Implementierungsentscheidung und keine allgemeine Garantie der API. Erklärt die Dokumentation nicht, wie der Fortschritt nach einer Unterbrechung wiederhergestellt werden kann, bitten Sie um eine Klärung. Ist das Verfahren dokumentiert, implementieren Sie es und legen Sie fest, wie ein abgeschlossener von einem ausstehenden Durchlauf unterschieden wird. Verwenden Sie den zuletzt beobachteten Wert nicht als gültigen Wiederaufnahmepunkt, wenn der Dienst dies nicht unterstützt.

Ein weiterer praktischer Fall sind Datensätze, die bei der Verarbeitung verschiedener Teile doppelt zu sein scheinen. Entfernen Sie sie nicht automatisch und nehmen Sie nicht an, dass der Dienst Duplikate garantiert ausschließt. Vergleichen Sie zunächst die verfügbaren Kennungen und prüfen Sie den Vertrag sowie den Verlauf des Durchlaufs, um zu verstehen, was geschehen ist. Entscheiden Sie, dass die Anwendung wiederholte Kennungen auf eine bestimmte Weise behandeln soll, dokumentieren Sie diese Regel als eigene Entscheidung und prüfen Sie, ob dadurch keine Datensätze verborgen werden, die erhalten bleiben sollten.

Diese Prüfungen helfen bei der Diagnose eines Durchlaufs, garantieren aber für sich genommen keine vollständige Erfassung. Die richtige Strategie hängt von den Regeln des Endpoints und den Anforderungen der Integration ab; die verfügbaren Informationen stützen keine universelle Strategie für Wiederaufnahme oder Deduplizierung.

• Halten Sie bei einer Unterbrechung Diagnoseinformationen fest und prüfen Sie, ob sich der Durchlauf über den dokumentierten Mechanismus wiederaufnehmen lässt.
• Vergleichen Sie bei wiederholt auftretenden Datensätzen die Kennungen und prüfen Sie, wie sie abgerufen wurden, bevor Sie entscheiden, ob sie verworfen werden.
• Verwechseln Sie einen Durchlauf, bei dem Daten gespeichert wurden, nicht mit einem Durchlauf, der das Abschlusssignal erreicht hat.

Prüfungen zur Kontrolle des Ergebnisses

Als allgemeine technische Kontrollen können Sie protokollieren, welcher Vorgang ausgeführt wurde, wann er begonnen und geendet hat, wie viele Anfragen zum Durchlauf gehörten und welches Signal als Abschluss interpretiert wurde. Diese Angaben helfen, den Ablauf nachzuvollziehen und einen Lesevorgang mit einem anderen zu vergleichen. Sie sind kein automatischer Integritätsnachweis; der Detaillierungsgrad sollte zu Ihrem System passen.

Sie können außerdem die Kennungen der empfangenen Elemente prüfen und das Ergebnis mit einer vom Dienst mitgeteilten Anzahl vergleichen, sofern es eine solche gibt. Behandeln Sie Abweichungen als Anlass für Nachforschungen und nicht als unmittelbaren Beweis: Eine Anzahl kann als Referenz nützlich sein, belegt für sich allein aber nicht, dass alle erwarteten Elemente vorhanden sind. Ebenso beweist das Fehlen doppelter Kennungen nicht, dass keine Datensätze fehlen.

Halten Sie getrennt fest, welche Angaben vom Dienst stammen und welche Ihre Integration selbst berechnet. Notieren Sie zum Beispiel, ob eine Zahl aus einer dokumentierten Antwort stammt oder die Gesamtzahl der von Ihrem Prozess gezählten Elemente ist. So vermeiden Sie, eine lokale Messung als Garantie des Anbieters darzustellen, und können Abweichungen leichter eingrenzen.

• Protokollieren Sie, welche Abschlussbedingung erreicht wurde und welche Probleme während des Durchlaufs aufgetreten sind.
• Untersuchen Sie abweichende Anzahlen oder wiederholte Kennungen, statt sie automatisch zu verbergen.
• Verwenden Sie eine Referenzanzahl nur, wenn der Dienst sie bereitstellt, und behandeln Sie sie nicht als vollständigen Integritätsnachweis.

Was Sie bei einer Integration mit Apification Cloud prüfen sollten

Apification ermöglicht die Integration von Cloud und seinen Diensten über REST API, OpenAPI, Webhooks, iFrame und JavaScript. Diese Optionen beschreiben Integrationsmöglichkeiten. Für sich genommen legen sie nicht fest, wie ein bestimmter Vorgang paginiert wird oder welche Parameter, Fortsetzungssignale oder Garantien gelten.

Wenn Sie das Auslesen von Ressourcen automatisieren, wenden Sie das allgemeine Verfahren erst an, nachdem Sie den technischen Vertrag des verwendeten Vorgangs ermittelt haben. Halten Sie den Endpoint, die dokumentierte Fortsetzungsmethode und die Abschlussbedingung fest. Ist eine dieser Regeln nicht verfügbar, sollte die Integration sie nicht durch eine erfundene Konvention ersetzen.

Mit Apification Cloud lassen sich Dateien, Dienste und Projekte in einem versionierten und gemeinsam nutzbaren Arbeitsbereich organisieren. Diese Funktion bedeutet nicht, dass ein Endpoint eine bestimmte Art der Paginierung verwendet. Unterscheiden Sie die Plattformfunktionen von den Regeln, die in der Dokumentation des abgefragten Dienstes festgelegt sein müssen.

• Prüfen Sie den Fortsetzungsmechanismus und die Abschlussbedingung in der zugehörigen technischen Dokumentation.
• Schreiben Sie Apification Cloud keine Paginierung, Wiederaufnahme oder Integritätsgarantien zu, sofern diese nicht dokumentiert sind.

Häufige Fragen