83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# API-Abdeckung – Snapshot 0.1.0-alpha.5
|
||
|
||
HTTP-Publish-Endpunkte liefern nach Outbox-Commit **202** mit `receipt.id`.
|
||
`Idempotency-Key` dedupliziert pro Quelle/Kanal. Details: [OPERATIONS.md](OPERATIONS.md).
|
||
|
||
## Ingress
|
||
|
||
| Oberfläche | Stand | Hinweise |
|
||
|---|---|---|
|
||
| ntfy POST/PUT Text | funktionsfähig | `/ntfy/{topic}` und `/in/ntfy/{topic}` |
|
||
| ntfy JSON Publish | funktionsfähig | `/ntfy` und `/in/ntfy`, `topic` erforderlich |
|
||
| ntfy GET Trigger | funktionsfähig | `trigger`, `send`, `publish` |
|
||
| ntfy Auth | Basis | Bearer; Basic-Password wird als Topic-Token geprüft |
|
||
| Gotify POST message | funktionsfähig | `/message` und `/in/gotify/message`; Token via Query/Header/Bearer |
|
||
| Gotify vollständige Response-/Extras-Kompatibilität | geplant | M2 |
|
||
| Webhook JSON/Form/Text | funktionsfähig | `/in/webhook/{channel}` |
|
||
|
||
## Zusätzliche Ausgänge (Provider-Erweiterung)
|
||
|
||
| Provider | Stand | Umfang |
|
||
|---|---|---|
|
||
| Discord | implementiert | Execute Webhook, Text, `wait=true`, keine Mentions, Dry-Run |
|
||
| HTTP-Webhook | implementiert | POST JSON, optional Bearer-Token, Timeout, Dry-Run |
|
||
| SMTP | implementiert | TLS/STARTTLS, MIME-Text, Plain-Auth |
|
||
| ntfy / Gotify | implementiert | JSON-Publish bzw. POST message mit App-Token |
|
||
| IMAP-Eingang | implementiert | TLS, UID-/UIDVALIDITY-Checkpoint, MIME-Text |
|
||
| Discord-Eingang | implementiert | `POST /in/discord`, signierte Slash-Commands und PING |
|
||
|
||
Konfiguration: `outbounds[]`; Regeln referenzieren einen Ausgang über `outbound_id`
|
||
und `target: discord|webhook|smtp|ntfy|gotify`. Administration über `GET/PUT /ui/api/config`,
|
||
Vorschau über `POST /ui/api/preview`.
|
||
|
||
## Betrieb und Administration
|
||
|
||
| Endpunkt | Funktion |
|
||
|---|---|
|
||
| `GET /readyz` | SQLite-Erreichbarkeit |
|
||
| `GET /metrics` | Prometheus-Zustandsmetriken; Metrics-Bearer-Token oder Admin-Session |
|
||
| `GET /ui/api/csrf` | CSRF-Token für schreibende Admin-Aufrufe |
|
||
| `GET /ui/api/deliveries?offset=0` | Zustellhistorie, 50 Einträge je Seite, Zähler und Mail-Abrufstatus |
|
||
| `GET /ui/api/deliveries/{id}/attempts` | Letzte 200 Versuchsereignisse |
|
||
| `POST /ui/api/deliveries/{id}/retry` | Nur fehlgeschlagene Aufträge erneut versuchen |
|
||
|
||
## Divera247 v2
|
||
|
||
`kind` ist `alarms`, `news` oder `events`, soweit die jeweilige Operation von Divera247 dokumentiert ist.
|
||
|
||
| Operation | Client-Methode | Stand |
|
||
|---|---|---|
|
||
| Liste | `List` | implementiert |
|
||
| Erstellen | `Create` | implementiert, durch Mapping genutzt |
|
||
| Einzelobjekt | `Get` | implementiert |
|
||
| Bearbeiten | `Update` | implementiert |
|
||
| Löschen | `Delete` | implementiert |
|
||
| Archivieren | `Archive` | implementiert |
|
||
| Als gelesen markieren | `Read` | implementiert |
|
||
| Rückmeldung | `Confirm` | implementiert |
|
||
| Reichweite | `Reach` | implementiert |
|
||
| Rückmeldungen zurücksetzen | `ResetResponses` | implementiert |
|
||
| PDF/Download | `Download` | implementiert |
|
||
| Anhang | `AddAttachment` | implementiert |
|
||
| Alarm-Liste inkl. `closed` | `AlarmList` | implementiert |
|
||
| Alarm schließen/öffnen | `CloseAlarm` | implementiert |
|
||
| Event ICS | `EventICS` | implementiert |
|
||
| Pull All | `PullAll` | implementiert |
|
||
| Pull Vehicle Status | `PullVehicleStatus` | implementiert |
|
||
| beliebiger API-Pfad | `Request` | implementiert (Escape Hatch) |
|
||
|
||
## Divera247 v3
|
||
|
||
Die offizielle v3-Spezifikation ist als Beta gekennzeichnet. `GET /api/v3/user-cluster-relations` ist als `ListUserClusterRelations` typisiert, wird für die WebUI aber nur noch als Fallback verwendet. Ein gültiger v2-Accesskey kann für v3 trotzdem HTTP 403 erhalten. Primäre Personenquelle ist daher `GET /api/v2/pull/all`: `data.ucr` liefert die erreichbaren User-Cluster-Relationen/Einheiten und `data.cluster.consumer` die Benutzer-Stammdaten der jeweils aktiven Einheit. Das Gateway lädt bei Mehrfacheinheiten die einzelnen UCRs über den v2-Parameter `ucr` und bewahrt die numerischen Consumer-Keys als UCR-IDs für gezielte Alarmierung.
|
||
|
||
## Quellenbasis der Implementierung
|
||
|
||
- Divera247 interaktive API: `https://api.divera247.com/`
|
||
- Divera247 OpenAPI v2 Alarm: `https://api.divera247.com/docs/api_v2_alarm.yaml`
|
||
- Divera247 OpenAPI v2 News: `https://api.divera247.com/docs/api_v2_news.yaml`
|
||
- Divera247 OpenAPI v2 Event: `https://api.divera247.com/docs/api_v2_event.yaml`
|
||
- Divera247 OpenAPI v2 Pull: `https://api.divera247.com/docs/api_v2_pull.yaml`
|
||
- Divera247 OpenAPI v3: `https://api.divera247.com/docs/api_v3.yaml`
|
||
- ntfy Publish API: `https://docs.ntfy.sh/publish/`
|
||
- Gotify API: `https://gotify.net/api-docs`
|