🟡 Paging und Sortierung

Dieses Kapitel erklärt zwei grundlegende Mechanismen der dataCycle API, die bei der Arbeit mit größeren Ergebnismengen eine zentrale Rolle spielen:

Paging – zur technischen Aufteilung von Ergebnissen in Seiten
Sortierung – zur fachlich definierten Reihenfolge der Inhalte

Beide Konzepte verfolgen unterschiedliche Ziele und sollten bewusst und getrennt voneinander verstanden werden.

Überblick

Wenn ein Endpoint viele Inhalte enthält, liefert die API diese nicht auf einmal aus. Stattdessen kannst du steuern:

wie viele Inhalte pro Request geliefert werden (Paging)
in welcher Reihenfolge sie erscheinen (Sortierung)

👉 Paging dient der technischen Navigation durch große Datenmengen 👉 Sortierung definiert die fachliche Ordnung der Ergebnisse

Paging – Inhalte seitenweise abrufen

Paging teilt große Ergebnismengen in kleinere, klar definierte Seiten auf.

Warum Paging notwendig ist

Paging sorgt dafür, dass:

Responses überschaubar bleiben
Clients planbar mit Daten arbeiten können
Nutzer:innen nicht unnötig viele Daten laden

Paging ist damit ein zentrales Werkzeug für Stabilität, Kontrolle und Skalierbarkeit bei der Nutzung der API.

Standardverhalten

Ohne explizite Paging-Parameter gilt:

es wird eine systemseitige Standard-Seitengröße verwendet
die konkrete Anzahl der Elemente ist nicht garantiert

👉 Best Practice: Paging immer explizit setzen.

Paging-Parameter

Paging erfolgt über den Parameter page.

Parameterübersicht:

page[number] – aktuelle Seite (beginnend bei 1)
page[size] – Anzahl der Elemente pro Seite

Beispiel: Erste Seite mit 10 Elementen

curl -H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?page[number]=1&page[size]=10"

Beispiel: Zweite Seite

curl -H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?page[number]=2&page[size]=10"

Response-Metadaten für Paging

Paging-Informationen werden im meta-Block der Response zurückgegeben, z. B.:

meta.page.number
meta.page.size
meta.page.totalPages
meta.page.totalElements

Zusätzlich stellt die API im links-Block Navigationshilfen bereit, z. B.:

links.next
links.prev
links.first
links.last

Diese Informationen sind wichtig für:

klassische Pagination
„Mehr laden“-Buttons
Endlos-Scrolling

Sortierung – Reihenfolge der Inhalte festlegen

Sortierung bestimmt, in welcher Reihenfolge Inhalte ausgeliefert werden.

Im Gegensatz zum Paging ist Sortierung keine Performance-Optimierung, sondern ein fachliches Ordnungswerkzeug.

Grundprinzip

Sortierung erfolgt über den Parameter sort
Standardsortierungen können endpoint-spezifisch sein
mehrere Sortierkriterien sind möglich

Sortieren nach Attributen

Aufsteigend sortieren:

sort=name

Absteigend sortieren:

sort=-name

Beispiel: Veranstaltungen nach Startdatum (neueste zuerst)

curl -H "Authorization: Bearer {TOKEN}" \
"{BASE_URL}/api/v4/endpoints/{ENDPOINT}?sort=-startDate"

Mehrere Sortierkriterien

Mehrere Felder werden durch Komma getrennt:

sort=-startDate,name

Bedeutung:

zuerst nach startDate absteigend
dann nach name aufsteigend

Typische Anwendungsfälle

Veranstaltungen nach Datum

sort=startDate

Neueste Inhalte zuerst

sort=-created

Alphabetische Listen

sort=name

Zusammenspiel von Paging und Sortierung

Paging ohne stabile Sortierung ist problematisch.

Warum?

die Reihenfolge kann sich zwischen Requests ändern
Inhalte können doppelt erscheinen oder fehlen

👉 Best Practice: Paging immer mit expliziter Sortierung kombinieren.

Dabei geht es nicht um Performance, sondern um Konsistenz, Vorhersehbarkeit und saubere Nutzerführung.

Kurz zusammengefasst

Paging begrenzt die Anzahl der Inhalte pro Request
page[number] und page[size] steuern die Seitennavigation
Sortierung legt die fachliche Reihenfolge der Inhalte fest
sort steuert die Reihenfolge, - kennzeichnet absteigend
Paging sollte immer mit stabiler Sortierung kombiniert werden

➡️ Im nächsten Kapitel geht es um Arbeiten mit Inhalten und konkrete Request-Beispiele.