DDI/docs/API.md

REST-API

Die vollständige, verbindliche Beschreibung ist die OpenAPI-Spezifikation server/api/openapi.yaml (ADR 0012, ADR 0019). Dieses Dokument erklärt nur die übergreifenden Regeln.

Grundlagen

• Basis-URL: https://<server>/api/v1
• Format: JSON (application/json), Felder in snake_case
• CSV-Export und -Import: text/csv, Audit-Export zusätzlich als JSON Lines

Anmeldung und Sitzung

1. POST /auth/login mit {"username", "password"} setzt das Sitzungs-Cookie ddi_session (HttpOnly, SameSite=Lax, Secure bei HTTPS) und liefert das CSRF-Token.
2. Ist für das Konto TOTP aktiv, ist die Sitzung zunächst mfa_required: true. Erst POST /auth/totp/verify mit {"code"} schließt die Anmeldung ab.
3. Muss das Passwort geändert werden (must_change_password), ist bis zu POST /auth/password nur die Passwortänderung erlaubt.
4. Single Sign-On: Der Browser ruft GET /auth/oidc/start auf und landet nach dem Identitätsanbieter über GET /auth/oidc/callback wieder in der Anwendung.

Jede zustandsändernde Anfrage (POST, PUT, DELETE) braucht den Header X-CSRF-Token: <csrf_token aus der Sitzung>. Anfragen von fremden Seiten (Origin/Sec-Fetch-Site) werden abgelehnt.

Sitzungen enden nach 12 Stunden oder nach 1 Stunde Inaktivität (konfigurierbar), bei Abmeldung, Passwortänderung (andere Sitzungen) und Deaktivierung des Kontos.

Rollen

Recht	Viewer	Operator	Admin
Netze, Adressen, Zonen, Records, Cluster, TSIG-Schlüssel (ohne Geheimnis), Lizenzstatus ansehen, exportieren, eigene Filter	✓	✓	✓
Netze, Adressen, Zonen und Records ändern, Import		✓	✓
Revisionen erzeugen, ausrollen, zurückrollen		✓	✓
Cluster und TSIG-Schlüssel verwalten, Geheimnis eines Schlüssels anzeigen, Agents, Generator-Einstellungen			✓
Benutzer, SSO, Lizenz verwalten, Audit-Log			✓

GET /auth/session liefert die effektiven Rechte (permissions).

Fehler

Fehler sind Problem-Dokumente nach RFC 9457 (application/problem+json):

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "validation_failed",
  "detail": "validation failed",
  "request_id": "5f2c…",
  "problems": [{ "code": "mac_required", "field": "mac" }]
}

• code ist stabil und Teil des Vertrags; die Oberfläche übersetzt ihn. detail ist Englisch und nur für Logs gedacht.
• problems listet Feldfehler mit eigenem code, optional field und params.
• request_id entspricht dem Header X-Request-ID und findet sich in den Server-Logs wieder.

Wichtige Statuscodes: 401 (nicht angemeldet, mfa_required), 403 (forbidden, csrf, license_read_only, password_change_required), 404, 409 (Konflikt, z. B. network_overlap, version_conflict), 422 (Validierung), 429 (zu viele Anmeldeversuche, mit Retry-After).

Schreibschutz durch die Lizenz

Ist der Server schreibgeschützt (siehe LICENSING.md), antworten alle ändernden Endpunkte mit 403 license_read_only. Lesen, Export, Anmeldung, eigene Filter und die Lizenzverwaltung bleiben erlaubt.

Gleichzeitige Änderungen

Netze, Adressen, Cluster, TSIG-Schlüssel, Zonen und Records tragen eine version. Änderungen (PUT) müssen die gelesene Version mitsenden; hat jemand anderes inzwischen geändert, antwortet der Server mit 409 version_conflict.

Adresstabelle

GET /addresses filtert, sortiert und paginiert serverseitig:

Parameter	Bedeutung
q	Suche in IP (Präfix), MAC (beliebige Schreibweise), Hostname, FQDN, Beschreibung, Verantwortlichem
network_id, type (mehrfach), tag, lease_state	Filter
sort, order	Sortierung (ip, type, mac, hostname, fqdn, network, last_seen, lease, updated_at; asc/desc)
limit (max. 1000), offset	Seite

Die Antwort enthält items und total. GET /addresses/export akzeptiert dieselben Filter und liefert CSV.

POST /addresses/preview beschreibt vorab die Auswirkungen einer Änderung auf DNS und DHCP (z. B. dhcp.add_reservation). Massenänderungen (/addresses/bulk) und CSV-Import (/addresses/import, mit dry_run=true zur Prüfung) gelten ganz oder gar nicht; Probleme werden pro Adresse bzw. Zeile gemeldet.

Geheimnisse

TSIG-Schlüssel und HA-Passwörter erzeugt der Server selbst (ADR 0023). Die API liefert sie nur an einer Stelle aus: GET /tsig-keys/{id}/secret (Recht settings.admin, jeder Abruf steht im Audit-Log – ohne das Geheimnis). Dateien mit Schlüsselmaterial erscheinen in Vorschau, Revision, Diff und offenen Änderungen mit secret: true und leerem Inhalt; Diffs nennen für sie nur den Status. Das HA-Passwort eines DHCP-Clusters wird nie angezeigt.

Ziele von Revisionen

Dateien in Vorschau, Revision und Diff tragen ein target: leer für die Standardgruppe (Agents ohne Cluster), sonst die Agent-ID eines Cluster-Mitglieds. targets beschreibt die Ziele mit Rolle, Cluster und Mitgliedsrolle zum Zeitpunkt der Revision. Ein Agent erhält die Dateien seines Ziels, wenn die Revision eines hat, sonst die der Standardgruppe.

Betriebsendpunkte

Außerhalb von /api/v1, ohne Anmeldung:

Pfad	Zweck
GET /healthz	Prozess lebt
GET /readyz	bereit (Datenbank erreichbar)
GET /metrics	Prometheus-Metriken