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

Rezepte

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

Rezept: Alle Nutzer synchronisieren

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

Wann nutzen: Nächtlicher Identity-Sync mit der Nutzerverwaltung als Quelle der Wahrheit dafür, wer in Fuxam existiert.

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

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

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 verwalten.

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:

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

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.

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:

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

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.

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

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.

loop pages:
  response = GET list
  if status == 429:
    sleep(Retry-After)
    retry same request
  process response.data
  advance cursor
# 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.

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).
  • Öffnen Sie nach dem Kodieren eines Rezepts die passende Referenzkarte im Browse-Abschnitt der Übersicht, 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 und Kurse.

Verwandte Seiten

War diese Seite hilfreich?