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, Lizenzstatus ansehen, exportieren, eigene Filter	✓	✓	✓
Netze und Adressen ändern, Import		✓	✓
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 und Adressen 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.

Betriebsendpunkte

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

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