Eine API, die Listen zurückgibt, muss begrenzen, wie viele Elemente sie pro Antwort ausliefert. Ohne Paginierung kann eine Abfrage unnötig viele Ressourcen verbrauchen, die Latenz erhöhen und sich für integrierende Anwendungen schwer handhaben lassen. Die Entscheidung beschränkt sich nicht auf die Wahl einer Syntax: Das Verfahren beeinflusst, welche Elemente Verbraucher bei Änderungen an den Daten sehen, wie sie durch die Ergebnisse navigieren und welche Garantien sie erwarten können.
Die beiden gängigsten Optionen sind die Offset-Paginierung, bei der angegeben wird, wie viele Datensätze übersprungen werden, und die Cursor-Paginierung, bei der eine Referenz zum Fortsetzen ab einer bestimmten Position dient. Die Wahl hängt vom Nutzungsmuster und den benötigten Garantien ab, nicht davon, dass eine Strategie grundsätzlich besser wäre.
Was eine paginierte Antwort gewährleisten sollte
Bevor Sie sich für ein Verfahren entscheiden, definieren Sie den Vertrag der Sammlung. Legen Sie mindestens die maximale Seitengröße, die Reihenfolge der Elemente, die Anforderung der nächsten Seite und das Verhalten fest, wenn keine weiteren Ergebnisse vorhanden sind. Außerdem sollten Sie angeben, wie Paginierung mit Filtern und Sortierung kombiniert wird.
Die Reihenfolge muss deterministisch sein. Eine Sortierung ausschließlich nach einem Datum kann beispielsweise mehrere Datensätze mit demselben Wert ergeben. Wenn die Sortierung nicht festlegt, wie solche Gleichstände aufgelöst werden, können verschiedene Anfragen Elemente an unterschiedlichen Positionen zurückgeben. Ein zusätzliches eindeutiges Kriterium, etwa die Datensatz-ID, sorgt für eine klar definierte Reihenfolge.
Eine hilfreiche Antwort kann neben den Elementen eine Referenz zum Fortsetzen sowie Metadaten wie die tatsächlich verwendete Seitengröße enthalten. Nicht alle Clients müssen die Gesamtzahl der Ergebnisse kennen: Ihre Berechnung kann Kosten verursachen, und bei häufig wechselnden Daten ist die Zahl möglicherweise schnell veraltet. Geben Sie nur die Informationen zurück, die für den Anwendungsfall erforderlich sind.
Offset-Paginierung: einfach zu einer Position springen
Bei der Offset-Paginierung fordert der Client eine Anzahl von Elementen und die Zahl der zu überspringenden Elemente an. Eine beispielhafte Anfrage lautet: „Gib 20 Elemente ab Datensatz 40 zurück.“ Das Modell ist leicht zu erklären und eignet sich für Oberflächen mit nummerierten Seiten, Sprüngen zu einer bestimmten Seite oder direktem Zugriff auf weiter hinten in der Liste stehende Ergebnisse.
Der wichtigste Vorteil ist der einfache Vertrag. Clients können Links zu Seiten erstellen, und Entwicklungsteams können mit Bereichen arbeiten. Für kleine oder relativ stabile Sammlungen kann das ebenfalls ausreichen, insbesondere wenn die direkte Navigation tatsächlich benötigt wird.
Die Grenzen zeigen sich, wenn sich die Daten zwischen zwei Anfragen ändern. Angenommen, der Client lädt die erste Seite und bevor er die nächste anfordert, wird am Anfang der Sortierreihenfolge ein Element eingefügt. Dann kann der folgende Offset einen bereits angezeigten Datensatz erneut liefern. Wird vor der angeforderten Position ein Element gelöscht, kann ein Datensatz übersprungen werden, der noch nicht ausgeliefert wurde. Offset allein gewährleistet keine konsistente Ansicht einer dynamischen Sammlung.
Außerdem kann eine Anfrage für sehr weit hinten liegende Positionen je nach Datenbank, Abfrage und Indizes viele Datensätze durchlaufen oder verwerfen müssen. Das gilt nicht in jedem System in gleicher Weise: Messen Sie das Verhalten anhand repräsentativer Abfragen. Werden tiefe Seiten langsam, begrenzen Sie die maximal überspringbare Anzahl oder prüfen Sie ein anderes Verfahren.
Cursor-Paginierung: ab einer Position fortfahren
Bei der Cursor-Paginierung stellt die Antwort eine Referenz bereit, die der Client für den nächsten Ergebnisabschnitt mitsendet. Der Cursor steht für eine Position innerhalb einer Sortierreihenfolge. Er kann sich beispielsweise auf den Sortierwert und eine ID stützen, die Gleichstände auflöst. Der Client muss nicht wissen, wie diese Referenz intern aufgebaut ist.
Damit das Verfahren verlässlich funktioniert, muss die Abfrage zwischen den Anfragen dieselbe Sortierreihenfolge beibehalten. Ein Cursor auf Grundlage eines Datums benötigt ein zusätzliches Kriterium, wenn mehrere Zeilen dasselbe Datum haben. Gleichzeitige Änderungen können weiterhin beeinflussen, welche Elemente auf späteren Seiten erscheinen. Ein Verfahren, das sich an einer sortierten Position orientiert, vermeidet jedoch üblicherweise die Verschiebungen, die beim Überspringen einer bestimmten Anzahl von Zeilen entstehen. Das ist nicht automatisch gleichbedeutend mit einem unveränderlichen Snapshot: Eine solche Garantie muss zusätzlich entworfen und dokumentiert werden.
Der Cursor sollte für den Verbraucher undurchsichtig sein. Er kann Positionsdaten codieren, doch Codierung bedeutet weder Verschlüsselung noch Schutz. Nehmen Sie ohne geeigneten Schutz keine sensiblen Informationen auf und prüfen Sie, ob der Cursor zur Abfrage, zum Benutzer und zum jeweiligen Autorisierungskontext passt. Legen Sie außerdem fest, ob er abläuft und welche Antwort der Client erhält, wenn er nicht mehr verwendet werden kann.
Diese Option eignet sich für sequenzielle Durchläufe, Feeds, große Kataloge und Prozesse, die Ergebnisse Schritt für Schritt verarbeiten, ohne zu einer beliebigen Seite zu springen. Dafür wird die direkte Navigation komplizierter, und Format, Validierung sowie Kompatibilität der Cursor müssen sorgfältig gestaltet werden.
Praktische Kriterien für die Auswahl
Berücksichtigen Sie die Anforderungen der Verbraucher und die Eigenschaften des Datensatzes. Die Entscheidung lässt sich folgendermaßen zusammenfassen:
- Wählen Sie Offset, wenn nummerierte Seiten oder direkte Sprünge wichtig sind, die Sammlung begrenzt ist oder Änderungen während der Navigation akzeptable Auswirkungen haben.
- Wählen Sie Cursor, wenn Ergebnisse sequenziell durchlaufen werden, die Sammlung stark wachsen kann oder Einfügungen und Löschungen Verschiebungen zwischen Seiten unerwünscht machen.
- Vergleichen Sie die tatsächlichen Kosten anhand repräsentativer Abfragen und Seitengrößen. Strategie, Indizes, Filter und Datenbank beeinflussen die Leistung.
- Berücksichtigen Sie das Integrationsmuster: Ein Batch-Export muss möglicherweise zuverlässig fortgesetzt werden können; bei einer Verwaltungsoberfläche kann der Sprung zu einer bestimmten Seite wichtiger sein.
Vermischen Sie die beiden Modelle nicht, ohne ihren jeweiligen Geltungsbereich zu erläutern. Offset für einige Abfragen und Cursor für andere anzubieten, kann sinnvoll sein. Der Vertrag jeder Sammlung muss jedoch klar dokumentiert werden. Stellen Sie einen Cursor auch nicht als Garantie vollständiger Konsistenz dar, wenn das Design lediglich eine Position speichert und sich die Sammlung weiterhin ändert.
Filter, Sortierung und Grenzwerte: der vollständige Vertrag
Der Cursor und die nächste Seite müssen zu denselben Filtern und derselben Sortierung gehören wie die erste Antwort. Ändert der Client diese Parameter, muss er einen neuen Durchlauf beginnen und darf keine Referenz wiederverwenden, die eine andere Abfrage repräsentiert. Die API kann diese Kombination ablehnen oder Cursor ausgeben, die den erforderlichen Kontext für eine Prüfung enthalten.
Dokumentieren Sie eine Standardgröße und eine maximale Seitengröße pro Anfrage. Eine Begrenzung verhindert übermäßig große Antworten, sollte aber zum erwarteten Verbrauch passen und Clients nicht zu einer übermäßig hohen Zahl von Aufrufen zwingen. Geben Sie an, was bei fehlenden, ungültigen oder über dem Maximum liegenden Werten geschieht. Ein Limit anzuwenden oder einen Fehler zurückzugeben sind mögliche Optionen; entscheidend ist ein konsistentes Verhalten.
Auch für die vom Benutzer angeforderte Sortierung sind klare Einschränkungen nötig. Akzeptieren Sie nur zugelassene Felder und Sortierrichtungen, legen Sie ein deterministisches Kriterium zum Auflösen von Gleichständen fest und verhindern Sie, dass eine geänderte Sortierung versehentlich mit einem vorherigen Cursor kombiniert wird. Diese Details verringern doppelte Ergebnisse, Auslassungen und schwer zu optimierende Abfragen.
Migration ohne Unterbrechung bestehender Clients
Wenn eine API bereits Offset-Paginierung anbietet, können Änderungen an der Antwort oder das Entfernen von Parametern Anwendungen und Integrationen beeinträchtigen. Ermitteln Sie vor einer Migration die Clients, Nutzungsmuster, tiefen Seiten und beobachteten Fehler. Reichen die Telemetriedaten nicht aus, instrumentieren Sie Anfragen, um zu erkennen, welche Parameter verwendet werden. Beachten Sie dabei die geltenden Datenschutz- und Aufbewahrungsrichtlinien.
- Definieren Sie den neuen Vertrag: Sortierung, Filter, maximale Seitengröße, undurchsichtiges Cursorformat und Verhalten bei ungültigen Cursorwerten.
- Führen Sie die Kompatibilität ausdrücklich ein: beispielsweise über einen neuen Pfad oder Parameter oder über einen dokumentierten Übergang, bei dem das bisherige Verfahren vorübergehend erhalten bleibt.
- Testen Sie gleichzeitige Änderungen, Gleichstände in der Sortierung, die letzte Seite, geänderte Filter sowie fehlerhafte Cursor und deren Wiederverwendung außerhalb des passenden Kontexts.
- Beobachten Sie Akzeptanz und Leistung, bevor Sie die alte Option entfernen. Kommunizieren Sie die Änderungen und stellen Sie den Verbrauchern Anleitungen zur Aktualisierung bereit.
Vermeiden Sie, dass eine Antwort je nach Client unbemerkt eine andere Bedeutung erhält oder der Server einen mehrdeutigen Parameter auf zwei Arten interpretiert. Kompatibilität muss überprüfbar sein. Fristen oder Bedingungen für die Entfernung müssen dokumentiert und dürfen nicht nur vermutet werden.
Checkliste für die Entscheidung
- Müssen Verbraucher direkt zu einer nummerierten Seite springen können?
- Ändern sich die Daten während des Durchlaufs, und welche Folgen haben Wiederholungen oder Auslassungen?
- Ist die Reihenfolge deterministisch und gibt es ein eindeutiges Kriterium zum Auflösen von Gleichständen?
- Wurden tiefe Abfragen und realistische Seitengrößen gemessen?
- Sind Filter, Grenzwerte, Fehler und die Wiederverwendung von Cursorwerten definiert?
- Gibt es eine Kompatibilitätsstrategie und eine Möglichkeit, die Einführung zu beobachten?
Wenn die direkte Navigation zentral ist und die Sammlung überschaubar bleibt, kann Offset eine sinnvolle Wahl sein. Überwiegt der sequenzielle Durchlauf und machen Umfang oder Änderungen das Überspringen von Elementen anfällig, passt Cursor häufig besser. Dokumentieren Sie zuerst die benötigten Garantien und wählen Sie anschließend das Verfahren: So erfüllt die API die tatsächlichen Anforderungen ihrer Verbraucher und kann sich ohne Überraschungen weiterentwickeln.