Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

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=100 für Bulk-Sync-Jobs; nutzen Sie kleinere Limits beim interaktiven Erkunden.
  • Stoppen Sie strikt bei has_more === false — nehmen Sie nicht an, dass ein leeres data-Array allein den Durchlauf beendet, ohne die Paginierung zu prüfen.
  • Kombinieren Sie fields mit Paginierung, wenn Sie nur IDs für eine Join-Tabelle brauchen.
  • Respektieren Sie Rate Limits beim Durchlaufen vieler Seiten; beachten Sie Retry-After bei 429.
  • 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.

Verwandte Seiten

War diese Seite hilfreich?