Loheide-eu-mitarbeiterplatt.../docs/API.md
Friederich Loheide 7b20d40994
Some checks failed
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 10m32s
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 10m37s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 17m19s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 17m21s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 16m33s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 16m27s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 13m30s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 14m15s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 49s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m18s
App zeigt Plugins ohne neue App-Version (0.60.0)
API: Feed, Aufgaben, Schnellzugriffe, Menü; Einmal-Link für eingebettete
Portalseiten ohne Kopf- und Fußzeile.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 19:46:34 +00:00

8 KiB
Raw Permalink 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, plugins: aktive Plugins, die die Person nutzen darf (z. B. ["news", "chat"])
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) mit likes, liked und comments (Anzahl; null = Kommentare aus)
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
GET /ideas?status=&sortierung=&q= Ideenbox (20 je Seite); status: new, review, done, rejected
GET /ideas/{id} Idee mit Beschreibung, Rückmeldung (status_note) und Kommentaren (comment_list)
POST /ideas einreichen: { "title": "…", "body": "…", "anonymous": false }
POST/DELETE /ideas/{id}/support unterstützen bzw. zurücknehmen → { data: { supported, supports } }
POST /ideas/{id}/report melden: { "reason": "offensive|personal|confidential|spam|other", "note": "…", "comment_id": null }
POST /ideas/{id}/comments kommentieren: { "body": "…" }
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, Umfragen und Ideen kommen aus den gleichnamigen Plugins – ist ein Plugin deaktiviert, fehlen seine Endpunkte (404). Welche Plugins aktiv und für die Person freigegeben sind, steht in /me unter plugins.

Die Kunden-Plugins Nachrichten (chat), Diskussionsgruppen (gruppen) und Kleinanzeigen (kleinanzeigen) bringen eigene Endpunkte unter /chat, /gruppen und /kleinanzeigen mit (siehe README des jeweiligen Plugins). Bilder und Anhänge liefern sie in der API mit Adressen, die das Token der App annehmen.

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.

Startseite der App: Feed, Aufgaben, Anwendungen, Menü (ab 0.60.0)

Was Plugins im Portal beisteuern, kommt über diese allgemeinen Endpunkte – neue Plugins erscheinen so in der App, ohne dass die App neu gebaut werden muss.

Methode Pfad Inhalt
GET /api/v1/feed?vor=<Zeitpunkt> { items, next } – Einträge wie im Feed der Mitarbeiter-App (kind, actor, title, text, image_url, images, url, stats, cta, like). like.url zeigt auf einen API-Endpunkt (mode: toggle → POST/DELETE, mode: reaction → POST {emoji})
GET /api/v1/tasks { data: [...] } – Meine Aufgaben (title, meta, url, icon, due, overdue)
GET /api/v1/apps { data: [...] } – Schnellzugriffe der Person (label, subtitle, url, icon, logo_url, category, pinned, new_tab)
GET /api/v1/menu { data: [...] } – Hauptmenü wie im Portal, je Person gefiltert (label, href, icon, children)
POST /api/v1/web-session { path: "/verleih" } { data: { url } } – Einmal-Link (2 Minuten), der die Portalseite eingebettet öffnet: angemeldet, ohne Kopf- und Fußzeile. Für alles, wofür die App keinen eigenen Bildschirm hat

Adressen (url, href) sind Portalpfade. Die App öffnet bekannte Bereiche in eigenen Bildschirmen (z. B. /neuigkeiten/…, /termine/…, /chat), alles andere eingebettet.

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.