# 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. **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 | `/me` | eigenes Profil, Anzahl ungelesener Benachrichtigungen | | 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`) | | GET | `/events` | anstehende Termine | | GET | `/events/{id}` | Termin mit Beschreibung (HTML) und Kalenderdatei (`ics_url`) | Neuigkeiten und Termine kommen aus den gleichnamigen Plugins – ist ein Plugin deaktiviert, fehlen seine Endpunkte (`404`). 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. Native Apps (App Store, Google Play) können die API nutzen; Push für native Apps (Apple/Google-Dienste) ist noch nicht angebunden.