Loheide-eu-mitarbeiterplatt.../docs/API.md
Friederich Loheide 9703a4c3f2
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 6m39s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 6m12s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 7m26s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 7m7s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 9m56s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 10m12s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 8m58s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 8m52s
CI / Bekannte Sicherheitslücken in Paketen (pull_request) Successful in 48s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m9s
App kennt aktive Plugins (0.43.0)
- /api/v1/me liefert „plugins“: aktive Plugins, die die Person nutzen darf
  (Rollen-Ausschluss beachtet) – die App blendet Nachrichten, Gruppen und
  Kleinanzeigen danach ein
- docs/API.md: Feld beschrieben, Hinweis auf die API der Kunden-Plugins

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 20:24:06 +00:00

107 lines
6.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`
```json
{ "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) |
| 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.
## 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:
```php
// 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.