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
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>
123 lines
8 KiB
Markdown
123 lines
8 KiB
Markdown
# 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) 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:
|
||
|
||
```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.
|