Phase 8 Mobil: REST-API, Web-Push, installierbare App (0.25.0)
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m54s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 4m0s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 4m54s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 4m50s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 7m48s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 7m38s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 6m56s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 7m5s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m17s
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 3m54s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 4m0s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 4m54s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 4m50s
CI / PHP 8.3 / mysql:8.0 (pull_request) Failing after 7m48s
CI / PHP 8.4 / mysql:8.0 (pull_request) Failing after 7m38s
CI / PHP 8.4 / mysql:8.4 (pull_request) Failing after 6m56s
CI / PHP 8.3 / mysql:8.4 (pull_request) Failing after 7m5s
CI / Build-Artefakte aktuell (pull_request) Successful in 1m17s
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
232dc5c59c
commit
f11a3e24b3
201 changed files with 3604 additions and 427 deletions
73
docs/API.md
Normal file
73
docs/API.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# 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. **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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue