Fuxam API v4
Branchenübliche REST-API zur Integration mit der Fuxam-Plattform — Authentifizierung, Paginierung, Fehler und Endpunktreferenz.
Die Fuxam API v4 ist eine versionierte REST-API, mit der Ihre Institution Studierendeninformationssysteme, Identity Provider, Reporting-Tools und eigene Middleware mit denselben Daten verbinden kann, die Ihre Mitarbeitenden in Fuxam Web verwalten. Jeder Endpunkt teilt einen Satz Konventionen für Authentifizierung, Antwortform, Paginierung, Fehler und Concurrency — sobald Sie die Muster auf dieser Seite kennen, können Sie sie auf Nutzer, Kurse, Curricula und den Rest des Ressourcenkatalogs anwenden.
Base URL: https://fuxam.app/api/v4
Warum Institutionen integrieren
Universitäten laufen selten auf einem einzigen System. Zulassung kann in einem Produkt liegen, HR in einem anderen und die Lernplattform in einem dritten. Die Fuxam API existiert, damit diese Systeme autoritative Daten austauschen können, ohne doppelte Dateneingabe:
- Identitäten bereitstellen und synchronisieren mit denselben Nutzern, die Ihre Administratoren in der Nutzerverwaltung verwalten.
- Akademische Struktur lesen und aktualisieren — Kurse, Module, Curricula, Studiengänge und Semester — im Einklang mit FuxamCMS und FuxamLMS.
- Operative Workflows automatisieren wie Raum-Lookups, Termindaten und Fortschrittsreads, die sonst manuelle Exporte erfordern würden.
Die Integration ist institutionsbezogen: Zugangsdaten, die Sie unter Organisation → API-Integrationen erstellen, authentifizieren sich als Integration dieser Institution, nicht als einzelner Mitarbeiter.
Wie das in Fuxam passt
Die API ist die programmatische Oberfläche von Konzepten, die Sie bereits aus dem Web-Handbuch kennen. Ein Nutzer in der API ist dieselbe Identität wie in der Nutzerverwaltung; eine Kurs-ID adressiert denselben Kurs, den Mitarbeitende in der Kursverwaltung oder im LMS öffnen.
| API-Ressourcenbereich | Verwandte Themen im Web-Handbuch |
|---|---|
| Nutzer, Rollen, Nutzergruppen | Nutzerverwaltung, Rollen und Berechtigungen, Nutzergruppen |
| Kurse, Inhaltsblöcke, Fortschritt | Kursverwaltung, LMS-Kurse, Inhalt |
| Module, Curricula, Studiengänge, Semester | Akademische Struktur, Studiengänge und Kohorten |
| Räume, Termine | Räume, Kalender |
Schlüsselkonzepte
| Konzept | Bedeutung |
|---|---|
| Integration | Ein unter Organisation → API-Integrationen registrierter API-Client mit clientId und clientSecret. |
| Response envelope | Erfolgreiche Antworten wrappen den Payload in { data, meta } (Einzelressource) oder { data, pagination, meta } (Listen). |
| Cursor pagination | Keyset-Paging mit ?limit= und ?cursor= — niemals Offset/page-basiert. |
| Sparse fieldsets | Optionales ?fields=, um nur die benötigten Eigenschaften anzufordern. |
| Problem details | Fehler nutzen RFC 7807 application/problem+json mit einem stabilen maschinenlesbaren code. |
| Idempotency | Create-(POST)-Anfragen können Idempotency-Key senden, um doppelte Ressourcen bei Retry zu vermeiden. |
| Optimistic concurrency | Schreibvorgänge auf Einzelressourcen nutzen ETag / If-Match, damit gleichzeitige Updates sich nicht still überschreiben. |
Konventionen auf einen Blick
- Ein Response-Envelope überall:
{ data, meta }für eine Einzelressource,{ data, pagination, meta }für Listen. - Cursor-Paginierung:
?limit=&cursor=; Antworten tragenpagination.next_cursor,pagination.has_moreundpagination.limit. Keine Offsets. - RFC-7807-Fehler (
application/problem+json) mit stabilem, maschinenlesbarem Top-Level-code. - Idempotente Creates über den Header
Idempotency-Key. - Sparse Fieldsets über
?fields=id,email,…. - Optimistic Concurrency bei Schreibvorgängen auf Einzelressourcen:
GET-Antworten enthalten ein starkesETag; senden Sie es alsIf-MatchbeiPATCH,PUToderDELETEzurück.
Jede Antwort enthält ein meta-Objekt mit requestId, timestamp und version ("v4").
Typischer Anfragefluss
Authentifizierung
Alle Anfragen nutzen HTTP Basic Auth mit Ihren Integrations-Zugangsdaten (clientId:clientSecret, Base64-kodiert):
Authorization: Basic <base64(clientId:clientSecret)>
Erstellen Sie eine Integration unter Organisation → API-Integrationen, um clientId und clientSecret zu erhalten. API-Key-Berechtigungs-Scopes sind in v4 nicht implementiert — Basic Auth ist für die Integration Alles-oder-nichts.
Für eine vollständige Walkthrough zu Zugangsdaten und Sicherheitspraxis siehe Authentifizierung.
Response-Envelope
Einzelressource:
{
"data": { "id": "usr_123", "email": "user@example.com" },
"meta": {
"requestId": "req_1700000000000_abc123",
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v4"
}
}
Liste (mit Cursor-Paginierung):
{
"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"
}
}
Nutzen Sie ?fields=, um auf unterstützten Endpunkten ein Sparse Fieldset anzufordern. Details und Schleifenbeispiele finden Sie unter Paginierung und Filterung.
Cursor-Paginierung
Listenendpunkte akzeptieren die Query-Parameter ?limit= (1–100) und ?cursor=:
| Parameter | Beschreibung |
|---|---|
limit |
Seitengröße (1–100; Server-Default gilt, wenn weggelassen) |
cursor |
Undurchsichtiger Cursor aus pagination.next_cursor der vorherigen Seite |
Cursor sind HMAC-signiert und an Ihre Institution und Integration gebunden. Manipulierte oder fremde Cursor liefern 400 mit dem Code invalid_cursor. Die Paginierung nutzt Keyset-Cursor über (sortField, id) — niemals Offset-basiertes Paging.
Wenn pagination.has_more false ist, haben Sie die letzte Seite erreicht.
Fehlermodell (RFC 7807)
Alle Fehler verwenden application/problem+json mit type als URI https://fuxam.app/errors/{code}.
Es gibt zwei getrennte code-Namespaces:
- Der Top-Level-
codeist die geschlosseneApiErrorCode-Union — maschinenlesbar und stabil. - Jeder Eintrag in
errors[].codeist ein Zod-Issue-Code (z. B.invalid_string) mit einem RFC-6901-pointer(z. B./email).
{
"type": "https://fuxam.app/errors/resource_not_found",
"title": "Not Found",
"status": 404,
"code": "resource_not_found"
}
v4 sendet kein 403. Cross-Tenant-Zugriff liefert dasselbe 404 resource_not_found wie eine wirklich fehlende Ressource — Existenz wird nie preisgegeben. Validierungsfehler liefern HTTP 422.
Häufige Statuscodes: 200 Lesen/Aktualisieren, 201 erstellt, 204 gelöscht, 409 Konflikt oder laufender Idempotenz-Lock, 412 ETag-Mismatch, 428 fehlendes erforderliches If-Match, 429 Rate Limit (Retry-After beachten).
Vertiefte Abdeckung von Fehlerbehandlung, Idempotenz, Concurrency und Rate Limits finden Sie unter Fehler und Idempotenz.
Idempotenz
POST-Anfragen, die Ressourcen erstellen, akzeptieren einen Idempotency-Key-Header. Das erneute Senden desselben Schlüssels innerhalb des Idempotenzfensters liefert die zwischengespeicherte Antwort (einschließlich des ursprünglichen 201) zurück, ohne ein Duplikat zu erzeugen. Konfliktierende laufende Schlüssel können 409 zurückgeben.
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Optimistic Concurrency
GETs auf Einzelressourcen senden ein starkes ETag. Senden Sie es als If-Match bei PATCH, PUT oder DELETE zurück:
- 412
precondition_failed— die Ressource hat sich seit dem Lesen geändert. - 428
precondition_required—If-Matchwar erforderlich, fehlte aber.
Rate Limits
Jede Integration teilt sich ein Budget von 1000 Anfragen/min (gleitendes Fenster, Schlüssel aus Integration + Institution). Antworten enthalten RateLimit-*-Header; 429-Antworten enthalten Retry-After.
In diesem Abschnitt
Beginnen Sie mit den Leitfäden unten und nutzen Sie dann die Ressourcen-Karten für die Endpunktreferenz.
Erste Schritte
Integration erstellen, authentifizieren und erste Listenanfrage stellen.
Authentifizierung
Basic Auth, Zugangsdaten, Rotation und Sicherheitspraxis.
Paginierung und Filterung
Cursor, Sparse Fieldsets und Filtermuster.
Fehler und Idempotenz
Problem Details, Retries, ETags und Rate Limits.
Rezepte
End-to-End-Muster für Sync, Lookup und sichere Writes.
Wo Sie starten
- Folgen Sie Erste Schritte, um Zugangsdaten zu erstellen und
GET /usersaufzurufen. - Lesen Sie Authentifizierung, bevor Sie Secrets in der Produktion speichern.
- Nutzen Sie Paginierung und Filterung, wenn Sie große Sammlungen durchlaufen müssen.
- Wenden Sie Fehler und Idempotenz an, bevor Sie Create- oder Update-Automatisierung starten.
- Kopieren Sie ein Muster aus Rezepte und öffnen Sie dann die passende Endpunktreferenz unten.
Nach Ressource durchsuchen
Endpunktreferenzseiten sind nach Ressourcen-Tag gruppiert und in die Abschnitte unten organisiert. Diese Routen werden aus der OpenAPI-Spezifikation generiert.
Nutzer
Nutzer
Nutzerprofile, Mitgliedschaft, Lebenszyklus, Kontaktdaten
Rollen
Institutionsrollen und Nutzer-Rollenzuweisungen
Kurse
Kurse
Kurse (adressiert über id; Filter nach Code)
Inhaltsblöcke
Kurs-Inhaltsblöcke
Workbenches
Kurs-Workbenches
Nutzerfortschritt
Nutzerfortschritt über Inhaltsblöcke
Termine
Termine und Raumbuchungen
Akademisches
Kursmodule
Kursmodule, Versionen und Gruppen
Curricula
Curricula, Versionen und verschachtelte Struktur
Studiengänge
Studiengänge, Versionen, Kohorten
Organisationssemester
Chronologie akademischer Semester
Kohorten
Kohorten innerhalb von Studiengängen