# 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:///api/v1` ## Anmeldung Jede Anfrage trägt ein persönliches Zugangs-Token: Authorization: Bearer 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:///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": { "": "" \| ["…"] \| 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.