Loheide-eu-mitarbeiterplatt.../docs/API.md
Friederich Loheide 3f67fde50b
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 5m33s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 5m25s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 6m7s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 5m54s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 9m9s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 10m55s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 10m12s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 1m26s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 9m48s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m52s
Umfragen-Plugin (0.32.0)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 12:54:17 +00:00

5.5 KiB
Raw Blame History

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:

  1. In der App mit Portal-Passwort – POST /token

    { "email": "ada@example.org", "password": "…", "device_name": "iPhone von Ada" }
    

    Antwort 201: { "token": "1|…", "user": { … } }. Höchstens 10 Versuche je Minute.

  2. Über den Browser (Inhaus-App, klappt mit jedem Anmeldedienst) – Ablauf wie OAuth mit PKCE:

    1. Die App erzeugt einen geheimen code_verifier (43–128 Zeichen) und daraus code_challenge = base64url(sha256(code_verifier)) ohne =, dazu einen zufälligen state.
    2. Sie öffnet https://<portal>/app/verbinden?redirect_uri=inhaus://verbunden&device_name=…&code_challenge=…&state=… im Browser. Die Person meldet sich an und bestätigt.
    3. Das Portal leitet zurück an inhaus://verbunden?code=…&state=…. Der Code gilt 5 Minuten und nur einmal.
    4. POST /token/exchange mit { "code": "…", "code_verifier": "…" } → 201 wie bei POST /token.

    Erlaubt sind nur Rücksprung-Adressen mit dem Schema inhaus://. Für die Entwicklung mit Expo Go zusätzlich INHAUS_APP_SCHEMES=inhaus,exp in der .env setzen.

  3. 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 /config ohne Anmeldung: Name, Hausfarbe, Logo, Symbol, Anmeldewege, connect_url
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); likes, liked
POST/DELETE /news/{slug}/like Herz geben bzw. zurücknehmen → { data: { liked, likes } }
POST /push/devices App-Gerät für Push anmelden: { "token": "ExponentPushToken[…]", "platform": "ios", "name": "…" }
DELETE /push/devices App-Gerät abmelden: { "token": "…" }
GET /events anstehende Termine, je mit eigenem Anmeldestand (registration)
GET /events/{id} Termin mit Beschreibung (HTML), Kalenderdatei (ics_url) und registration
POST/DELETE /events/{id}/registration an- bzw. abmelden ({ "note": "…" } optional) → { message, data: registration }
GET /polls Umfragen: { data: { open: […], closed: […] } }
GET /polls/{id} Umfrage mit Fragen, eigenem Stand (voted, can_vote) und – falls freigegeben – results
POST /polls/{id}/vote abstimmen: { "answers": { "<frage-id>": "<antwort-id>" | ["…"] | 3 | "Text" } }

registration ist null ohne Anmeldung, sonst { enabled, open, capacity, confirmed, free, waitlist, waiting, status, position, note, deadline } – status ist null, "confirmed" oder "waitlist", position der Platz auf der Warteliste.

Neuigkeiten, Termine und Umfragen 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.

Die Inhaus-App (App Store, Google Play) meldet ihr Gerät mit POST /push/devices an. Der Versand läuft über den Push-Dienst von Expo, der an Apple und Google weiterleitet; übertragen werden Titel, Kurztext und Link (data.url, ein Pfad im Portal). Abgemeldete Geräte entfernt das Portal selbst. Wird ein App-Zugang entzogen, fällt auch das Gerät weg.