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

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 tragen pagination.next_cursor, pagination.has_more und pagination.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 starkes ETag; senden Sie es als If-Match bei PATCH, PUT oder DELETE zurü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-code ist die geschlossene ApiErrorCode-Union — maschinenlesbar und stabil.
  • Jeder Eintrag in errors[].code ist 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-Match war 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.

Wo Sie starten

  1. Folgen Sie Erste Schritte, um Zugangsdaten zu erstellen und GET /users aufzurufen.
  2. Lesen Sie Authentifizierung, bevor Sie Secrets in der Produktion speichern.
  3. Nutzen Sie Paginierung und Filterung, wenn Sie große Sammlungen durchlaufen müssen.
  4. Wenden Sie Fehler und Idempotenz an, bevor Sie Create- oder Update-Automatisierung starten.
  5. 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

Kurse

Akademisches

Einrichtungen

Zeiterfassung

Verzeichnis

War diese Seite hilfreich?