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>
8 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{ "email": "ada@example.org", "password": "…", "device_name": "iPhone von Ada" }Antwort
201:{ "token": "1|…", "user": { … } }. Höchstens 10 Versuche je Minute. -
Über den Browser (Inhaus-App, klappt mit jedem Anmeldedienst) – Ablauf wie OAuth mit PKCE:
- Die App erzeugt einen geheimen
code_verifier(43–128 Zeichen) und darauscode_challenge = base64url(sha256(code_verifier))ohne=, dazu einen zufälligenstate. - 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. - Das Portal leitet zurück an
inhaus://verbunden?code=…&state=…. Der Code gilt 5 Minuten und nur einmal. POST /token/exchangemit{ "code": "…", "code_verifier": "…" }→201wie beiPOST /token.
Erlaubt sind nur Rücksprung-Adressen mit dem Schema
inhaus://. Für die Entwicklung mit Expo Go zusätzlichINHAUS_APP_SCHEMES=inhaus,expin der.envsetzen. - Die App erzeugt einen geheimen
-
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.