itsdave/msp

Fork 0

mirror of https://github.com/itsdave-de/msp.git synced 2026-08-14 07:30:05 -03:00

Files

T

Dave 1fca135a83 chore: commit uncommitted production changes for v16 migration

2026-03-07 09:47:25 +01:00

11 KiB

Raw Blame History

Backup API - Admin API Dokumentation

Dokumentation der Admin-Endpoints für die Entwicklung eines Web-Interfaces.

Base URL

https://backupapi.itsdave.de/api/v1

Authentifizierung

Alle Admin-Endpoints erfordern den X-Admin-Key Header:

X-Admin-Key: <ADMIN_KEY>

Fehler bei ungültigem Key:

HTTP 401
{"detail": "Invalid admin API key"}

Token-Verwaltung

Alle Tokens auflisten

GET /admin/tokens

Response:

{
  "tokens": [
    {
      "id": 1,
      "name": "prod-servers",
      "active": 1,
      "created_at": "2026-01-01 10:00:00",
      "token_hash_preview": "65248fa2...",
      "allowed_hosts": ["web*", "db-primary"]
    },
    {
      "id": 2,
      "name": "monitoring",
      "active": 1,
      "created_at": "2026-01-02 10:00:00",
      "token_hash_preview": "a1b2c3d4...",
      "allowed_hosts": []
    }
  ]
}

Feld	Typ	Beschreibung
`id`	int	Eindeutige Token-ID
`name`	string	Token-Name
`active`	int	1 = aktiv, 0 = deaktiviert
`created_at`	string	Erstellungszeitpunkt
`token_hash_preview`	string	Erste 8 Zeichen des Hashes
`allowed_hosts`	array	Host-Patterns (leer = alle Hosts erlaubt)

Token erstellen

POST /admin/tokens
Content-Type: multipart/form-data

Parameter	Typ	Pflicht	Beschreibung
`name`	string	Ja	Eindeutiger Name (max 100 Zeichen)

Request:

curl -X POST "$API/admin/tokens" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -F "name=webserver-prod"

Response (201):

{
  "status": "success",
  "message": "Token created successfully",
  "token_id": 5,
  "name": "webserver-prod",
  "token": "V56pLTCkJTr4weA6Nkmwuw_h4gPO4l6b4hPLvQisxfM",
  "warning": "Save this token now! It cannot be retrieved later."
}

Wichtig: Das token Feld wird nur einmal zurückgegeben! Es wird als SHA-256 Hash gespeichert und kann nicht wiederhergestellt werden.

Fehler (409):

{"detail": "Token name already exists"}

Token-Details abrufen

GET /admin/tokens/{token_id}

Response:

{
  "id": 1,
  "name": "prod-servers",
  "active": 1,
  "created_at": "2026-01-01 10:00:00",
  "token_hash_preview": "65248fa2...",
  "allowed_hosts": ["web*"],
  "backup_count": 156
}

Feld	Typ	Beschreibung
`backup_count`	int	Anzahl der Backups mit diesem Token

Fehler (404):

{"detail": "Token not found"}

Token deaktivieren

POST /admin/tokens/{token_id}/revoke

Deaktiviert ein Token. Das Token kann danach nicht mehr zur Authentifizierung verwendet werden.

Response:

{"status": "success", "message": "Token 'prod-servers' revoked"}

Fehler (400):

{"detail": "Token is already revoked"}

Token aktivieren

POST /admin/tokens/{token_id}/activate

Reaktiviert ein zuvor deaktiviertes Token.

Response:

{"status": "success", "message": "Token 'prod-servers' activated"}

Fehler (400):

{"detail": "Token is already active"}

Token löschen

DELETE /admin/tokens/{token_id}

Löscht ein Token unwiderruflich. Host-Bindings werden automatisch mitgelöscht.

Response:

{"status": "success", "message": "Token 'prod-servers' deleted"}

Host-Binding Verwaltung

Tokens können auf bestimmte Hosts beschränkt werden. Ein Token ohne Bindings hat Zugriff auf alle Hosts.

Patterns

Pattern	Beschreibung
`webserver01`	Exakter Match
`web*`	Alle Hosts die mit "web" beginnen
`*-prod`	Alle Hosts die mit "-prod" enden
`db-?`	Einzelnes Zeichen Wildcard
`*`	Alle Hosts (explizit)

Host-Bindings anzeigen

GET /admin/tokens/{token_id}/hosts

Response:

{
  "token_id": 1,
  "token_name": "prod-servers",
  "hosts": [
    {"id": 1, "hostname_pattern": "web*", "created_at": "2026-01-07 20:00:00"},
    {"id": 2, "hostname_pattern": "db-primary", "created_at": "2026-01-07 20:00:00"}
  ]
}

Host-Binding hinzufügen

POST /admin/tokens/{token_id}/hosts
Content-Type: multipart/form-data

Parameter	Typ	Pflicht	Beschreibung
`hostname_pattern`	string	Ja	Hostname oder Pattern

Request:

curl -X POST "$API/admin/tokens/1/hosts" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -F "hostname_pattern=web*"

Response:

{"status": "success", "message": "Host pattern 'web*' added to token 'prod-servers'"}

Fehler (409):

{"detail": "Host pattern already exists for this token"}

Host-Binding entfernen

DELETE /admin/tokens/{token_id}/hosts/{hostname_pattern}

Request:

curl -X DELETE "$API/admin/tokens/1/hosts/web*" \
  -H "X-Admin-Key: $ADMIN_KEY"

Response:

{"status": "success", "message": "Host pattern 'web*' removed from token 'prod-servers'"}

Backup-Verwaltung

Alle Backups auflisten

GET /admin/backups

Parameter	Typ	Default	Beschreibung
`hostname`	string	-	Filter nach Hostname
`backup_type`	string	-	Filter nach Typ
`token_name`	string	-	Filter nach Token
`from_date`	string	-	Von Datum (YYYY-MM-DD)
`to_date`	string	-	Bis Datum (YYYY-MM-DD)
`limit`	int	1000	Max. Ergebnisse (max 10000)
`offset`	int	0	Offset für Pagination

Response:

{
  "backups": [
    {
      "id": 6,
      "hostname": "webserver01",
      "backup_type": "full",
      "log_type": "json",
      "token_name": "prod-servers",
      "created_at": "2026-01-07 19:34:45",
      "size": 1524
    }
  ],
  "count": 1,
  "total": 156,
  "limit": 1000,
  "offset": 0
}

Einzelnes Backup abrufen

GET /admin/backups/{backup_id}

Response:

{
  "id": 6,
  "hostname": "webserver01",
  "backup_type": "full",
  "log_content": {"status": "success", "files": 1523, "size_mb": 2300},
  "log_type": "json",
  "token_name": "prod-servers",
  "created_at": "2026-01-07 19:34:45"
}

Bei log_type: "json" wird log_content als JSON-Objekt zurückgegeben, sonst als String.

Backup löschen

DELETE /admin/backups/{backup_id}

Response:

{"status": "success", "message": "Backup 6 deleted"}

Statistiken

Statistik-Übersicht

GET /admin/stats

Parameter	Typ	Beschreibung
`from_date`	string	Von Datum (YYYY-MM-DD)
`to_date`	string	Bis Datum (YYYY-MM-DD)

Response:

{
  "total_backups": 156,
  "unique_hosts": 12,
  "by_type": [
    {"backup_type": "full", "count": 45},
    {"backup_type": "incremental", "count": 89},
    {"backup_type": null, "count": 22}
  ],
  "by_token": [
    {"token_name": "prod-servers", "count": 120},
    {"token_name": "dev-servers", "count": 36}
  ],
  "by_day": [
    {"date": "2026-01-07", "count": 24},
    {"date": "2026-01-06", "count": 22}
  ]
}

Audit-Logs

Audit-Logs abrufen

GET /admin/audit

Parameter	Typ	Default	Beschreibung
`event_type`	string	-	Filter nach Event-Typ
`from_date`	string	-	Von Datum (YYYY-MM-DD)
`to_date`	string	-	Bis Datum (YYYY-MM-DD)
`limit`	int	100	Max. Ergebnisse (max 1000)

Event-Typen:

TOKEN_CREATED - Token erstellt
TOKEN_DELETED - Token gelöscht
TOKEN_REVOKED - Token deaktiviert
TOKEN_ACTIVATED - Token aktiviert
TOKEN_HOST_ADDED - Host-Binding hinzugefügt
TOKEN_HOST_REMOVED - Host-Binding entfernt
BACKUP_SUBMITTED - Backup hochgeladen
BACKUP_DELETED - Backup gelöscht
AUTH_FAILED - Authentifizierung fehlgeschlagen
ADMIN_AUTH_SUCCESS - Admin-Authentifizierung erfolgreich
ADMIN_AUTH_FAILED - Admin-Authentifizierung fehlgeschlagen
ACCESS_DENIED - Zugriff verweigert (Host-Binding)

Response:

{
  "audit_logs": [
    {
      "id": 15,
      "event_type": "TOKEN_CREATED",
      "details": "name=webserver-prod",
      "ip_address": "192.168.1.100",
      "created_at": "2026-01-07 20:20:38"
    }
  ]
}

Fehler-Codes

Code	Beschreibung
400	Ungültige Anfrage (z.B. Datumsformat, bereits aktiv/inaktiv)
401	Admin-Key ungültig
404	Ressource nicht gefunden
409	Konflikt (z.B. Name existiert bereits)
413	Datei zu groß
503	Admin API nicht konfiguriert

Beispiel: Kompletter Token-Workflow

API="https://backupapi.itsdave.de/api/v1"
ADMIN_KEY="your-admin-key"

# 1. Token erstellen
TOKEN_RESPONSE=$(curl -s -X POST "$API/admin/tokens" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -F "name=webserver-prod")
echo "$TOKEN_RESPONSE"
TOKEN_ID=$(echo "$TOKEN_RESPONSE" | jq -r '.token_id')

# 2. Host-Bindings hinzufügen
curl -s -X POST "$API/admin/tokens/$TOKEN_ID/hosts" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -F "hostname_pattern=web*"

curl -s -X POST "$API/admin/tokens/$TOKEN_ID/hosts" \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -F "hostname_pattern=nginx-*"

# 3. Token-Details prüfen
curl -s "$API/admin/tokens/$TOKEN_ID" \
  -H "X-Admin-Key: $ADMIN_KEY" | jq

# 4. Token deaktivieren (bei Bedarf)
curl -s -X POST "$API/admin/tokens/$TOKEN_ID/revoke" \
  -H "X-Admin-Key: $ADMIN_KEY"

# 5. Token reaktivieren
curl -s -X POST "$API/admin/tokens/$TOKEN_ID/activate" \
  -H "X-Admin-Key: $ADMIN_KEY"

# 6. Token löschen
curl -s -X DELETE "$API/admin/tokens/$TOKEN_ID" \
  -H "X-Admin-Key: $ADMIN_KEY"

JavaScript/Fetch Beispiele

const API = 'https://backupapi.itsdave.de/api/v1';
const ADMIN_KEY = 'your-admin-key';

const headers = {
  'X-Admin-Key': ADMIN_KEY
};

// Alle Tokens laden
async function getTokens() {
  const response = await fetch(`${API}/admin/tokens`, { headers });
  return response.json();
}

// Token erstellen
async function createToken(name) {
  const formData = new FormData();
  formData.append('name', name);

  const response = await fetch(`${API}/admin/tokens`, {
    method: 'POST',
    headers,
    body: formData
  });
  return response.json();
}

// Host-Binding hinzufügen
async function addHostBinding(tokenId, pattern) {
  const formData = new FormData();
  formData.append('hostname_pattern', pattern);

  const response = await fetch(`${API}/admin/tokens/${tokenId}/hosts`, {
    method: 'POST',
    headers,
    body: formData
  });
  return response.json();
}

// Token deaktivieren
async function revokeToken(tokenId) {
  const response = await fetch(`${API}/admin/tokens/${tokenId}/revoke`, {
    method: 'POST',
    headers
  });
  return response.json();
}

// Statistiken laden
async function getStats(fromDate, toDate) {
  const params = new URLSearchParams();
  if (fromDate) params.append('from_date', fromDate);
  if (toDate) params.append('to_date', toDate);

  const response = await fetch(`${API}/admin/stats?${params}`, { headers });
  return response.json();
}

// Backups mit Pagination laden
async function getBackups(page = 0, limit = 50, filters = {}) {
  const params = new URLSearchParams({
    limit: limit.toString(),
    offset: (page * limit).toString(),
    ...filters
  });

  const response = await fetch(`${API}/admin/backups?${params}`, { headers });
  return response.json();
}

11 KiB Raw Blame History

Backup API - Admin API Dokumentation

Base URL

Authentifizierung

Token-Verwaltung

Alle Tokens auflisten

Token erstellen

Token-Details abrufen

Token deaktivieren

Token aktivieren

Token löschen

Host-Binding Verwaltung

Patterns

Host-Bindings anzeigen

Host-Binding hinzufügen

Host-Binding entfernen

Backup-Verwaltung

Alle Backups auflisten

Einzelnes Backup abrufen

Backup löschen

Statistiken

Statistik-Übersicht

Audit-Logs

Audit-Logs abrufen

Fehler-Codes

Beispiel: Kompletter Token-Workflow

JavaScript/Fetch Beispiele

11 KiB

Raw Blame History