---
icon: book-open
title: Rezepte
description: Praktische Muster der Fuxam API v4 — Nutzer synchronisieren, Kurse nach Code suchen, sichere ETag-Updates und idempotente Creates.
---

Diese Rezepte sind End-to-End-Muster, die nur auf den dokumentierten v4-Konventionen aufbauen: Basic Auth, das Envelope `{ data, meta }`, Cursor-Paginierung, `Idempotency-Key` und `ETag` / `If-Match`. Nutzen Sie sie als Vorlagen in Ihrer Middleware; tauschen Sie Ressourcenpfade nach Bedarf und bestätigen Sie Feldnamen auf den generierten Endpunktreferenzseiten.

**Base URL:** `https://fuxam.app/api/v4`

## Warum Rezepte helfen

Referenzseiten zeigen jeweils eine Operation. Echte Integrationen verketten Operationen: list → filter → get → patch, oder create → retry. Die Muster unten kodieren diese Sequenzen, damit Uni-IT-Teams zuverlässige Sync-Jobs ausliefern können, ohne Concurrency- und Paginierungs-Randfälle neu zu entdecken.

## Bevor Sie beginnen

- Schließen Sie [Erste Schritte](/docs/de/api/getting-started) ab, damit Zugangsdaten funktionieren.
- Lesen Sie [Authentifizierung](/docs/de/api/authentication), [Paginierung und Filterung](/docs/de/api/pagination-and-filtering) und [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency).
- Halten Sie `CLIENT_ID` und `CLIENT_SECRET` in der Umgebung; hardcodieren Sie sie niemals in Scripts, die Sie committen.

```mermaid
flowchart LR
  Auth[Authentifizieren] --> List[Listen oder filtern]
  List --> Get[Abrufen per id]
  Get --> Write[Erstellen oder aktualisieren]
  Write --> Handle[Fehler und Retries behandeln]
```

## Rezept: Alle Nutzer synchronisieren

**Ziel:** Alle Nutzer mit Cursor-Paginierung in ein externes System ziehen.

**Wann nutzen:** Nächtlicher Identity-Sync mit der [Nutzerverwaltung](/docs/de/fuxam-web/base/user-management) als Quelle der Wahrheit dafür, wer in Fuxam existiert.

```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}&fields=id,email"
  else
    URL="${BASE}/users?limit=${LIMIT}&fields=id,email&cursor=${CURSOR}"
  fi

  RESP=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
    -H "Accept: application/json" "$URL")

  # Upsert each object in RESP.data into your SIS / directory mirror.
  printf '%s\n' "$RESP" | jq -c '.data[]'

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

Pseudocode:

```text
cursor = null
loop:
  response = GET /users?limit=100&fields=id,email[&cursor=cursor]
  upsert_all(response.data)
  if response.pagination.has_more is false: break
  cursor = response.pagination.next_cursor
```

:::tip
Sparse Fieldsets (`fields=id,email`) halten Payloads klein. Fügen Sie Felder nur hinzu, wenn Ihr Mirror sie braucht. Endpunktdetails: [Nutzer](/docs/de/api/users/users/list-users).
:::

## Rezept: Kurs nach Code suchen, dann per id lesen

**Ziel:** Einen menschenlesbaren Kurscode in eine stabile id auflösen und dann die volle Ressource abrufen.

**Wann nutzen:** Migrationen von v3 (wo Code-Adressierung üblicher war), SIS-Importe, die nur Kurscodes kennen, oder Verknüpfung zu Kursen, die Mitarbeitende in der [Kursverwaltung](/docs/de/fuxam-web/cms/courses-management) verwalten.

```bash
CODE="CS101"

LIST=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/courses?code=${CODE}&limit=25")

COURSE_ID=$(printf '%s' "$LIST" | jq -r '.data[0].id // empty')

if [ -z "$COURSE_ID" ]; then
  echo "No course found for code ${CODE}" >&2
  exit 1
fi

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D - \
  "https://fuxam.app/api/v4/courses/${COURSE_ID}"
```

HTTP-Sequenz:

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

```http
GET /api/v4/courses/{id} HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

:::note
In v4 werden Kurse über **id** adressiert. Filtern mit `GET /courses?code=…` ist der dokumentierte Weg, diese id zu finden. Siehe [Kurse](/docs/de/api/courses/courses/list-courses).
:::

## Rezept: Ressource sicher mit ETag aktualisieren

**Ziel:** Eine Einzelressource ändern, ohne die gleichzeitige Bearbeitung einer anderen Person zu überschreiben.

**Wann nutzen:** Jedes automatisierte `PATCH`, `PUT` oder `DELETE` auf einer Einzelressource, die bei `GET` ein `ETag` sendet.

```bash
USER_ID="usr_123"

# 1) Read current version
HEADERS=$(mktemp)
BODY=$(mktemp)

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D "$HEADERS" \
  -o "$BODY" \
  "https://fuxam.app/api/v4/users/${USER_ID}"

ETAG=$(awk 'BEGIN{IGNORECASE=1} /^ETag:/{print $2}' "$HEADERS" | tr -d '\r')

# 2) Write with If-Match
HTTP_CODE=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -o /tmp/patch-response.json -w "%{http_code}" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  -d @patch-body.json \
  "https://fuxam.app/api/v4/users/${USER_ID}")

if [ "$HTTP_CODE" = "412" ]; then
  echo "precondition_failed — re-GET, merge, retry" >&2
  exit 1
fi
```

Pseudocode:

```text
resource, etag = GET /users/{id}          # capture ETag header
try:
  PATCH /users/{id} with If-Match: etag
catch 412 precondition_failed:
  resource, etag = GET /users/{id} again
  merge_changes(resource)
  retry PATCH with new etag
catch 428 precondition_required:
  ensure If-Match is sent
```

:::warning[412 nicht blind erneut versuchen]
Ein `412` bedeutet, dass sich die Ressource geändert hat. Erneut lesen und abgleichen, bevor Sie einen weiteren Schreibvorgang senden.
:::

## Rezept: Mit Idempotenz erstellen

**Ziel:** Eine Ressource einmal erstellen, auch wenn der HTTP-Client nach einem Timeout erneut versucht.

**Wann nutzen:** Provisioning-Jobs, Webhook-Verbraucher, die zweimal liefern können, jedes Create, das nicht duplizieren darf.

```bash
IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d @create-body.json \
  "https://fuxam.app/api/v4/users"
```

```http
POST /api/v4/users HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Accept: application/json

# Body: JSON create payload from the endpoint reference
```

Zu erwartendes Verhalten:

| Situation | Ergebnis |
|---|---|
| Erster erfolgreicher Create | `201` mit der neuen Ressource in `data` |
| Retry mit **demselben** Schlüssel und äquivalentem Create | Zwischengespeicherte Originalantwort (einschließlich `201`) — kein Duplikat |
| Konfliktierender laufender Schlüssel | Kann `409` liefern — warten und mit demselben Schlüssel erneut versuchen oder Konfliktbehandlung in Ihrem Job prüfen |

:::tip
Speichern Sie den Idempotenzschlüssel zusammen mit Ihrer Outbound-Job-ID, damit jeder Retry dieses Jobs den Schlüssel wiederverwendet.
:::

## Rezept: Rate Limits beim Paging behandeln

**Ziel:** Einen großen Sync abschließen, ohne dass der Job fehlschlägt, wenn Sie 1000 Anfragen/min erreichen.

```text
loop pages:
  response = GET list
  if status == 429:
    sleep(Retry-After)
    retry same request
  process response.data
  advance cursor
```

```bash
# Illustrative fragment — honor Retry-After from response headers
RETRY_AFTER=60
sleep "$RETRY_AFTER"
```

Kombinieren Sie das mit größeren `limit`-Werten, damit Sie weniger Anfragen pro vollem Durchlauf brauchen. Details: [Fehler und Idempotenz](/docs/de/api/errors-and-idempotency).

## Muster wählen

| Bedarf | Rezept |
|---|---|
| Verzeichnis spiegeln | Alle Nutzer synchronisieren |
| SIS kennt nur Kurscodes | Nach Code suchen, dann per id |
| Aktualisieren ohne UI-Edits zu überschreiben | Sicher mit ETag aktualisieren |
| Provisionieren ohne Duplikate | Mit Idempotenz erstellen |
| Großer Sync unter Last | Rate-Limit-bewusstes Paging |

## Best Practices über Rezepte hinweg

- Loggen Sie `meta.requestId` bei jeder Antwort.
- Bevorzugen Sie serverseitige Jobs gegenüber browserseitigen Aufrufen mit langlebigen Secrets.
- Trennen Sie Integrationen pro Workload, damit Rate Limits und Rotationen isoliert bleiben ([Authentifizierung](/docs/de/api/authentication)).
- Öffnen Sie nach dem Kodieren eines Rezepts die passende Referenzkarte im Browse-Abschnitt der [Übersicht](/docs/de/api/overview), um Request-/Response-Schemas zu bestätigen.

## Häufige Fallstricke

| Fallstrick | Besserer Ansatz |
|---|---|
| Sync mit `limit=1` | Bis zu `100` für Bulk-Jobs nutzen |
| Create ohne Idempotency-Key | Stets eine UUID pro logischem Create setzen |
| Patch ohne If-Match | Zuerst GET; ETag senden |
| Code als Primärschlüssel für Kurse annehmen | Code → id auflösen, dann id nutzen |

## FAQ

**Kann ich diese Rezepte auf Curricula oder Räume anpassen?**

Ja — Envelope, Paginierung, Auth, Idempotenz und ETag-Regeln sind gemeinsam. Ersetzen Sie Pfade durch die benötigte Ressource aus den Browse-Karten der Übersicht (zum Beispiel Curricula oder Räume) und bestätigen Sie Filter auf der Referenzseite dieses Endpunkts.

**Ersetzen Rezepte die OpenAPI-Referenz?**

Nein. Rezepte vermitteln Sequenzen und Konventionen. Feldbezogene Schemas leben auf den generierten Endpunktseiten wie [Nutzer](/docs/de/api/users/users/list-users) und [Kurse](/docs/de/api/courses/courses/list-courses).

## Verwandte Seiten

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

Zugangsdaten und erster GET.

**[Paginierung und Filterung](/docs/de/api/pagination-and-filtering)**

Cursor, Felder und Code-Filter.

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

Regeln zu 412, 429 und Idempotency-Key.

**[API-Übersicht](/docs/de/api/overview)**

Alle Ressourcen-Referenzgruppen durchsuchen.
