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
- Schließen Sie Erste Schritte ab, damit Zugangsdaten funktionieren.
- Lesen Sie Authentifizierung, Paginierung und Filterung und Fehler und Idempotenz.
- Halten Sie
CLIENT_IDundCLIENT_SECRETin der Umgebung; hardcodieren Sie sie niemals in Scripts, die Sie committen.
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.requestIdbei 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.