Paginierung und Filterung
Cursor-Paginierung, Sparse Fieldsets und Filtermuster für Listenendpunkte der Fuxam API v4 — limit, cursor, fields und Code-Filter.
Listenendpunkte in der Fuxam API v4 liefern Seiten von Ergebnissen im gemeinsamen Envelope { data, pagination, meta }. Sie bewegen sich durch eine Sammlung mit undurchsichtigen Cursorn, verkleinern optional jeden Payload mit Sparse Fieldsets und grenzen auf unterstützten Ressourcen die Ergebnisse mit Filtern wie dem Kurs-code ein.
Warum das wichtig ist
Institutionsverzeichnisse sind groß. Alle Nutzer oder Kurse in einer Antwort abzurufen, ist weder zuverlässig noch rücksichtsvoll gegenüber dem gemeinsamen Rate-Budget von 1000 Anfragen/min. Cursor-Paginierung liefert stabile, effiziente Seiten; Sparse Fieldsets reduzieren Bandbreite; Filter ermöglichen, einen einzelnen bekannten Kurs aufzulösen, ohne den gesamten Katalog zu durchlaufen.
Wie es zusammenhängt
Diese Seite baut auf den Konventionen der Übersicht und dem Erstseiten-Aufruf in Erste Schritte auf. Rate-Limit-Verhalten bei aggressiver Paginierung ist unter Fehler und Idempotenz abgedeckt.
Schlüsselkonzepte
| Begriff | Definition |
|---|---|
| Cursor / Keyset-Paginierung | Seiten werden durch einen undurchsichtigen Cursor über (sortField, id) identifiziert, nicht durch numerische Offsets. |
| limit | Query-Parameter für die Seitengröße: 1–100. Server-Default gilt, wenn weggelassen. |
| cursor | Undurchsichtiger Token aus pagination.next_cursor der vorherigen Seite. |
| has_more | Wenn false, haben Sie die letzte Seite erreicht. |
| Sparse fieldset | ?fields= mit den gewünschten Eigenschaftsnamen. |
| Filter | Ressourcenspezifische Query-Parameter (zum Beispiel code bei Kursen). |
Cursor-Paginierung — Referenz
| Parameter | Ort | Beschreibung |
|---|---|---|
limit |
Query | Seitengröße (1–100) |
cursor |
Query | Undurchsichtiger Cursor aus pagination.next_cursor der vorherigen Seite |
pagination.next_cursor |
Antwort | Als cursor in der nächsten Anfrage übergeben, wenn weitere Seiten existieren |
pagination.has_more |
Antwort | true, wenn eine weitere Seite verfügbar ist |
pagination.limit |
Antwort | Effektive Seitengröße für diese Antwort |
Beispiel einer Listenantwort:
{
"data": [{ "id": "usr_123" }, { "id": "usr_456" }],
"pagination": {
"next_cursor": "eyJpZCI6MTIzfQ==",
"has_more": true,
"limit": 25
},
"meta": {
"requestId": "req_1700000000000_abc123",
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v4"
}
}
Cursor-Sicherheit
Cursor sind HMAC-signiert und an Ihre Institution und Integration gebunden. Manipulierte, inhaltlich abgelaufene oder fremde Cursor liefern HTTP 400 mit dem Code invalid_cursor. Teilen Sie Cursor niemals über Integrationen hinweg und bearbeiten Sie ihren Inhalt nicht.
So durchlaufen Sie jede Seite
Pseudocode für einen vollständigen Sammlungssync:
#!/usr/bin/env bash
set -euo pipefail
BASE="https://fuxam.app/api/v4"
CURSOR=""
LIMIT=100
while true; do
if [ -z "$CURSOR" ]; then
URL="${BASE}/users?limit=${LIMIT}"
else
URL="${BASE}/users?limit=${LIMIT}&cursor=${CURSOR}"
fi
RESP=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" -H "Accept: application/json" "$URL")
# Process RESP.data in your language of choice, then:
HAS_MORE=$(printf '%s' "$RESP" | jq -r '.pagination.has_more')
CURSOR=$(printf '%s' "$RESP" | jq -r '.pagination.next_cursor // empty')
if [ "$HAS_MORE" != "true" ]; then
break
fi
done
HTTP-Form für Folge seiten:
GET /api/v4/users?limit=100&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
Sparse Fieldsets
Auf unterstützten Endpunkten fordern Sie nur die benötigten Felder an:
GET /api/v4/users?fields=id,email&limit=50 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
curl -sS \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Accept: application/json" \
"https://fuxam.app/api/v4/users?fields=id,email&limit=50"
Vorteile:
- Kleinere Payloads beim Sync großer Verzeichnisse
- Klarere Verträge in typisierten Clients (Sie dokumentieren, von welchen Feldern Sie abhängen)
- Weniger versehentliche Kopplung an Eigenschaften, die Sie nicht nutzen
Filterung
Filter sind ressourcenspezifisch. Ein dokumentiertes und häufig benötigtes Beispiel ist der Lookup von Kursen nach Code, danach Adressierung über id für Folgeaufrufe (wichtig bei Migration von v3).
GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
curl -sS \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Accept: application/json" \
"https://fuxam.app/api/v4/courses?code=CS101&limit=25"
Typischer Folgeschritt: nehmen Sie data[0].id aus der gefilterten Liste, dann GET /courses/{id} für das volle Einzelressourcen-Envelope (und ETag, wenn Sie aktualisieren). Siehe Rezepte für das End-to-End-Muster und Kurse für die Listenoperationsreferenz.
Kurse im Web-Handbuch sind dieselben Entitäten, die Mitarbeitende in der Kursverwaltung durchsuchen und im LMS öffnen.
Best Practices
- Bevorzugen Sie
limit=100für Bulk-Sync-Jobs; nutzen Sie kleinere Limits beim interaktiven Erkunden. - Stoppen Sie strikt bei
has_more === false— nehmen Sie nicht an, dass ein leeresdata-Array allein den Durchlauf beendet, ohne die Paginierung zu prüfen. - Kombinieren Sie
fieldsmit Paginierung, wenn Sie nur IDs für eine Join-Tabelle brauchen. - Respektieren Sie Rate Limits beim Durchlaufen vieler Seiten; beachten Sie
Retry-Afterbei429. - Behandeln Sie Cursor als undurchsichtige Secrets Ihrer Integration — loggen Sie sie nicht in öffentlichen Kanälen.
Häufige Fallstricke
| Fallstrick | Ergebnis | Abhilfe |
|---|---|---|
page / pageSize aus v3 verwenden |
Unerwartete Fehler oder ignorierte Parameter | Auf cursor / limit umstellen |
| Cursor einer anderen Integration wiederverwenden | 400 invalid_cursor |
Frische Liste mit eigenen Zugangsdaten starten |
| Offset-Stabilität annehmen | Doppelte oder fehlende Zeilen bei gleichzeitigen Writes | Keyset-Cursor reduzieren das bereits; Syncs trotzdem auf Eventual Consistency auslegen |
| Volle Objekte abrufen, wenn nur IDs nötig sind | Langsame Syncs, höherer Rate-Verbrauch | ?fields=id (und weitere benötigte Schlüssel) nutzen |
FAQ
Was ist die maximale Seitengröße?
limit akzeptiert 1–100. Werte außerhalb dieses Bereichs sollten als Client-Fehler behandelt werden — bleiben Sie im dokumentierten Bereich.
Kann ich zu Seite 10 springen?
Nein. Cursor-Paginierung unterstützt keine beliebigen Seitenzahlen. Gehen Sie vom Start vorwärts oder behalten Sie einen gespeicherten Cursor aus einem vorherigen Lauf desselben Durchlaufs.
Unterstützen alle Listenendpunkte dieselben Filter?
Nein. Filter sind pro Ressource. Nutzen Sie code bei Kursen wie dokumentiert; prüfen Sie die Referenzseite jedes Endpunkts auf weitere Query-Parameter.