Backup & Wiederherstellung API

ENTWURF — Nur für interne Entwicklerteams

Diese API-Referenz ist für interne Entwicklerteams bestimmt.

Übersicht

Was es ist: Die Backup & Wiederherstellung API bietet Endpunkte zum Erstellen, Herunterladen und Wiederherstellen von verschlüsselten Backups sowohl der Registry (Konfigurationsdaten) als auch des Datenspeichers (Entitäts-/Identitätsdaten). Backups sind verschlüsselte ZIP-Dateien, die durch KSUID identifiziert werden.

Quellen: src/registry/rest/rest.go, src/datastore/rest/rest.go

Authentifizierung

Alle Endpunkte erfordern JWT-Cookie- oder API-Token-Authentifizierung. Benutzeransprüche (Mandant, Identität, E-Mail) werden in die Backup-Metadaten eingebettet.

Endpunkte

Registry-Backup

Methode	Pfad	Beschreibung
POST	/internal/v1/registry/backup	Ein Registry-Konfigurationsbackup erstellen
POST	/internal/v1/registry/restore	Registry aus einer Backup-Datei wiederherstellen
GET	/internal/v1/registry/backup/:node/:backup	Eine Registry-Backup-Datei herunterladen

Datenspeicher-Backup

Methode	Pfad	Beschreibung
POST	/internal/v1/datastore/backup	Ein Datenspeicher-Entitäts-Backup erstellen
POST	/internal/v1/datastore/restore	Datenspeicher aus einer Backup-Datei wiederherstellen
GET	/internal/v1/datastore/backup/:node/:backup	Eine Datenspeicher-Backup-Datei herunterladen

---

POST /internal/v1/registry/backup

Ein verschlüsseltes Backup aller Registry-Konfigurationsdaten erstellen.

Anfrage:

POST /internal/v1/registry/backup
Content-Type: application/json
Authorization: Bearer <token>

{
  "secret": "strong-encryption-passphrase"
}

Anfragefelder:

Feld	Typ	Erforderlich	Beschreibung
secret	string	Ja	Verschlüsselungspassphrase für die Backup-ZIP. Muss die Passwort-Komplexitätsanforderungen erfüllen.

Antwort (200):

{
  "id": "2GxBsGZA8gGzJDqTnVfYstMeaXd",
  "node": "node-uuid",
  "date": 1707700800000
}

Antwortfelder:

Feld	Typ	Beschreibung
id	string	Backup-Identifikator (KSUID-Format)
node	string	Knoten-ID, auf dem das Backup erstellt wurde
date	int64	Zeitstempel der Backup-Erstellung (ms)

Backup-Metadaten (in der ZIP eingebettet): Mandanten-ID, Benutzeridentität, Benutzer-ID, E-Mail und Name aus der authentifizierten Sitzung.

---

POST /internal/v1/registry/restore

Registry-Konfiguration aus einer verschlüsselten Backup-Datei wiederherstellen. Wird als Multipart-Formular hochgeladen.

Anfrage:

POST /internal/v1/registry/restore
Content-Type: multipart/form-data
Authorization: Bearer <token>

Formularfelder:

Feld	Typ	Beschreibung
file	file	Die Backup-ZIP-Datei
secret	string	Entschlüsselungspassphrase (muss mit der beim Backup verwendeten übereinstimmen)

Antwort (200):

{
  "records": 245,
  "failed": 0,
  "error": ""
}

Antwortfelder:

Feld	Typ	Beschreibung
records	int64	Anzahl der wiederhergestellten Konfigurationsdatensätze
failed	int64	Anzahl der Datensätze, die nicht wiederhergestellt werden konnten
error	string	Fehlermeldung (leer bei Erfolg)

---

GET /internal/v1/registry/backup/:node/:backup

Eine zuvor erstellte Registry-Backup-Datei herunterladen.

Anfrage:

GET /internal/v1/registry/backup/:node/:backup
Authorization: Bearer <token>

Pfadparameter:

Parameter	Beschreibung
node	Knoten-ID, auf dem das Backup erstellt wurde
backup	Backup-ID (KSUID)

Antwort (200): Binäre ZIP-Datei.

Antwortheader:

Header	Wert
Content-Disposition	attachment; filename=hydden-tenant-{id}-{timestamp}.zip
Content-Type	application/octet-stream

---

POST /internal/v1/datastore/backup

Ein verschlüsseltes Backup aller Datenspeicher-Entitätsdaten erstellen.

Anfrage:

POST /internal/v1/datastore/backup
Content-Type: application/json
Authorization: Bearer <token>

{
  "secret": "strong-encryption-passphrase"
}

Antwort (200):

{
  "id": "2GxBsGZA8gGzJDqTnVfYstMeaXd",
  "node": "node-uuid",
  "date": 1707700800000
}

Gleiche Struktur wie die Registry-Backup-Antwort.

---

POST /internal/v1/datastore/restore

Datenspeicher-Entitätsdaten aus einer verschlüsselten Backup-Datei wiederherstellen.

Anfrage:

POST /internal/v1/datastore/restore
Content-Type: multipart/form-data
Authorization: Bearer <token>

Formularfelder: Gleich wie bei der Registry-Wiederherstellung (file + secret).

Antwort (200):

{
  "stores": 12,
  "records": 45230,
  "failed": 0,
  "error": ""
}

Antwortfelder:

Feld	Typ	Beschreibung
stores	int64	Anzahl der wiederhergestellten Datenspeicher
records	int64	Anzahl der wiederhergestellten Entitätsdatensätze
failed	int64	Anzahl der Datensätze, die nicht wiederhergestellt werden konnten
error	string	Fehlermeldung (leer bei Erfolg)

---

GET /internal/v1/datastore/backup/:node/:backup

Eine zuvor erstellte Datenspeicher-Backup-Datei herunterladen.

Anfrage:

GET /internal/v1/datastore/backup/:node/:backup
Authorization: Bearer <token>

Pfadparameter: Gleich wie beim Registry-Backup-Download.

Antwort (200): Binäre ZIP-Datei.

Antwortheader:

Header	Wert
Content-Disposition	attachment; filename=hydden-registry-{timestamp}.zip
Content-Type	application/octet-stream

---

Fehlerantworten

Status	Beschreibung
400	Ungültiger Anfragekörper, schwaches Verschlüsselungsgeheimnis oder beschädigte Backup-Datei
403	Authentifizierung fehlgeschlagen oder unzureichende Berechtigungen
404	Backup nicht gefunden (ungültige Knoten- oder Backup-ID)
500	Interner Serverfehler während der Backup-/Wiederherstellungsoperation

Verwandte Themen

• Registry-Konfiguration API — Konfigurations-CRUD-Operationen
• Datenspeicher API — Entitäts- und Shard-Verwaltung