---
icon: list-filter
title: Paginierung und Filterung
description: 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

```mermaid
flowchart TD
  Start[Listenanfrage] --> Page[data und pagination empfangen]
  Page --> More{has more}
  More -->|yes| Next[Anfrage mit next cursor]
  Next --> Page
  More -->|no| Done[Sammlung vollstaendig]
```

Diese Seite baut auf den Konventionen der [Übersicht](/docs/de/api/overview) und dem Erstseiten-Aufruf in [Erste Schritte](/docs/de/api/getting-started) auf. Rate-Limit-Verhalten bei aggressiver Paginierung ist unter [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency) 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:

```json
{
  "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.

:::info
Die v4-Paginierung ist **nicht** Offset-basiert. Es gibt kein `page` / `pageSize` (das gehörte zu v3). Nutzen Sie stets `cursor` und `limit`.
:::

## So durchlaufen Sie jede Seite

Pseudocode für einen vollständigen Sammlungssync:

```bash
#!/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:

```http
GET /api/v4/users?limit=100&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

:::tip
Speichern Sie den letzten erfolgreichen Cursor nur, wenn Sie einen **einzelnen** unterbrochenen Durchlauf mit derselben Integration fortsetzen. Für nächtliche Syncs starten Sie jeden Lauf von der ersten Seite, sofern Sie kein bewusstes inkrementelles Design haben.
:::

## Sparse Fieldsets

Auf unterstützten Endpunkten fordern Sie nur die benötigten Felder an:

```http
GET /api/v4/users?fields=id,email&limit=50 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

```bash
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

:::note
Feldnamen müssen mit der Endpunktdokumentation übereinstimmen. Wenn Sie `fields` weglassen, liefert der Endpunkt seine Standarddarstellung.
:::

## 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).

```http
GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

```bash
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](/docs/de/api/recipes) für das End-to-End-Muster und [Kurse](/docs/de/api/courses/courses/list-courses) für die Listenoperationsreferenz.

Kurse im Web-Handbuch sind dieselben Entitäten, die Mitarbeitende in der [Kursverwaltung](/docs/de/fuxam-web/cms/courses-management) durchsuchen und im [LMS](/docs/de/fuxam-web/lms/courses) ö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

**[Erste Schritte](/docs/de/api/getting-started)**

Erster Listenaufruf und erster Cursor.

**[Rezepte](/docs/de/api/recipes)**

Muster Sync-aller-Nutzer und Lookup-nach-Code.

**[Fehler und Idempotenz](/docs/de/api/errors-and-idempotency)**

Rate Limits beim Paging, invalid_cursor.

**[Kurse-Referenz](/docs/de/api/courses/courses/list-courses)**

Kurse listen und nach Code filtern.
