Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
3.2 KiB
REST-API (Version 1)
Für Apps und Anbindungen. Alle Antworten sind JSON, alle Texte deutsch. Es gelten dieselben Rechte und Zielgruppen wie im Portal – wer etwas im Portal nicht sieht, bekommt es auch über die API nicht (auch der Rollen-Ausschluss von Modulen gilt).
Basisadresse: https://<portal>/api/v1
Anmeldung
Jede Anfrage trägt ein persönliches Zugangs-Token:
Authorization: Bearer <token>
Accept: application/json
Ein Token bekommt man auf zwei Wegen:
- In der App mit Portal-Passwort –
POST /token
Antwort{ "email": "ada@example.org", "password": "…", "device_name": "iPhone von Ada" }201:{ "token": "1|…", "user": { … } }. Höchstens 10 Versuche je Minute. - Im Portal unter Profil bearbeiten → Benachrichtigungen & Apps → Zugang. Der Weg für alle, die sich über Microsoft, LDAP oder SAML anmelden (sie haben kein Portal-Passwort). Der Schlüssel wird nur einmal angezeigt.
DELETE /token meldet das aktuelle Gerät ab. Im Profil lassen sich Zugänge einzeln entfernen.
Tokens deaktivierter Konten gelten sofort nicht mehr.
Endpunkte
| Methode | Pfad | Inhalt |
|---|---|---|
| GET | /me |
eigenes Profil, Anzahl ungelesener Benachrichtigungen |
| GET | /notifications |
Benachrichtigungen (30 je Seite, ?page=), meta.unread |
| POST | /notifications/{id}/read |
eine als gelesen markieren |
| POST | /notifications/read |
alle als gelesen markieren |
| GET | /people?q= |
Personenverzeichnis (50 je Seite) |
| GET | /people/{id} |
Kontaktdaten und freigegebene Profilfelder |
| GET | /search?q= |
globale Suche (wie die Suche oben im Portal) |
| GET | /news?category= |
Neuigkeiten (20 je Seite) |
| GET | /news/{slug} |
Beitrag mit Inhalt als Blöcke (blocks) und reinem Text (text) |
| GET | /events |
anstehende Termine |
| GET | /events/{id} |
Termin mit Beschreibung (HTML) und Kalenderdatei (ics_url) |
Neuigkeiten und Termine kommen aus den gleichnamigen Plugins – ist ein Plugin deaktiviert,
fehlen seine Endpunkte (404).
Fehler: 401 ohne gültiges Token, 403 bei fehlendem Recht oder ausgeschlossenem Modul,
404 für Unbekanntes oder nicht Sichtbares, 422 mit errors bei ungültigen Angaben.
Plugins
Plugins ergänzen eigene Endpunkte mit einer Datei routes/api.php. Das Portal lädt sie unter
/api/v1, nur mit gültigem Token und unter Beachtung des Rollen-Ausschlusses:
// plugins/mav-kalender/routes/api.php
Route::get('/mav/sitzungen', [SitzungApiController::class, 'index']); // → GET /api/v1/mav/sitzungen
$request->user() ist die angemeldete Person; Rechte wie im Portal über $user->can(…).
Push-Benachrichtigungen
Im Browser und in der installierten Web-App (Android, Windows, macOS; iPhone/iPad ab iOS 16.4, wenn das Portal zum Home-Bildschirm hinzugefügt ist) schaltet jede Person Push je Gerät ein – über die Glocke oder unter Profil bearbeiten. Es kommen dieselben Hinweise wie in der Glocke. Technisch: Web-Push mit VAPID (RFC 8291/8292), Schlüssel entstehen automatisch, der Versand läuft über die Warteschlange (Cron nötig). Voraussetzung ist HTTPS.
Native Apps (App Store, Google Play) können die API nutzen; Push für native Apps (Apple/Google-Dienste) ist noch nicht angebunden.