Pagination

Wie du dich durch große Ergebnismengen der ENLYZE API blätterst.

List-Endpunkte der ENLYZE API geben Ergebnisse seitenweise zurück. Statt alle Datensätze auf einmal zu liefern, liefert die API eine Seite und einen Cursor, mit dem du die nächste Seite abrufst. Mit limit legst du fest, wie viele Datensätze eine Seite höchstens enthält.

So funktioniert die Pagination

Die ENLYZE API nutzt cursorbasierte Pagination. Der Ablauf ist immer gleich:

1. Rufe einen Listen-Endpunkt ohne cursor auf, um die erste Seite zu erhalten.

2. Lies den Wert metadata.next_cursor aus der Antwort.

3. Rufe denselben Endpunkt erneut auf und übergib diesen Wert als cursor-Parameter, um die nächste Seite zu erhalten.

4. Wiederhole Schritt 2 und 3, bis metadata.next_cursor den Wert null hat. Dann sind keine weiteren Daten mehr vorhanden.

Behalte bei Folgeanfragen alle übrigen Parameter (zum Beispiel Filter und limit) unverändert bei. Andernfalls ist der Cursor nicht mehr gültig.

Antwortstruktur

Jede seitenweise Antwort hat dieselbe Struktur:

Feld	Typ	Beschreibung
data	Array	Die Datensätze der aktuellen Seite.
metadata.next_cursor	String oder null	Fortsetzungspunkt für die nächste Seite. null, wenn keine weiteren Daten vorhanden sind.

Für die Anfrage steuerst du die Pagination über zwei Parameter:

Parameter	Ort	Beschreibung
cursor	Query	Startpunkt der abzurufenden Seite. Übergib den Wert aus metadata.next_cursor der vorherigen Antwort. Ohne cursor erhältst du die erste Seite.
limit	Query	Maximale Anzahl an Datensätzen pro Seite. Ohne limit enthält eine Seite bis zu 1000 Datensätze. 1000 ist gleichzeitig das Maximum.

Seitengröße mit limit steuern

Ein limit unter dem Standardwert verkleinert die Seite. Ein größeres ist nicht möglich, weil der Standardwert gleichzeitig das Maximum ist.

limit lässt sich mit cursor und mit allen Filtern kombinieren. Enthält die Ergebnismenge mehr Datensätze, als limit erlaubt, liefert die Antwort trotzdem einen next_cursor für die nächste Seite. Bei sortierten Endpunkten bezieht sich limit auf diese Reihenfolge: limit=1 liefert den ersten Datensatz der Sortierung.

Ein limit, das keine ganze Zahl ist, kleiner als 1 oder größer als das Maximum, weist die API mit dem Statuscode 422 ab (siehe Fehler).

Beim Endpunkt POST /v2/timeseries werden cursor und limit im Anfrage-Body übergeben, nicht als Query-Parameter. Dort zählt limit Zeilen der Zeitreihe: Ohne limit enthält eine Seite bis zu 10.000 Zeilen, und 10.000 ist auch das Maximum. Eine Zeile zählt auch dann, wenn alle angefragten Variablen darin null sind. Die Antwortstruktur mit data und metadata.next_cursor bleibt identisch.

Beispiel

Erste Seite abrufen:

GET https://app.enlyze.com/api/v2/production-runs

Antwort:

{
  "data": [
    { "uuid": "3f2a…" },
    { "uuid": "8b1c…" }
  ],
  "metadata": {
    "next_cursor": "eyJpZCI6MTQ4fQ"
  }
}

Nächste Seite abrufen, indem du next_cursor als cursor übergibst:

GET https://app.enlyze.com/api/v2/production-runs?cursor=eyJpZCI6MTQ4fQ

Um nur einen Datensatz abzurufen, zum Beispiel um zu prüfen, ob es überhaupt Produktionsläufe gibt, setze limit=1:

GET https://app.enlyze.com/api/v2/production-runs?limit=1

Auf der letzten Seite ist next_cursor gleich null:

{
  "data": [
    { "uuid": "d90e…" }
  ],
  "metadata": {
    "next_cursor": null
  }
}

Der Cursor ist ein undurchsichtiges Token. Verändere seinen Inhalt nicht und baue ihn nicht selbst zusammen. Verwende ausschließlich den Wert aus metadata.next_cursor.