Zum Hauptinhalt springen

Rückwärts-inkompatible API-Änderungen

Dieses Dokument beschreibt Breaking Changes für externe API-Endpunkte in verschiedenen Versionen von duplistatus. Externe API-Endpunkte sind solche, die für die Verwendung durch andere Anwendungen und Integrationen konzipiert sind (z. B. Homepage-Integration).

Übersicht

Dieses Dokument behandelt Breaking Changes an externen API-Endpunkten, die Integrationen, Skripte und Anwendungen beeinflussen, die diese Endpunkte nutzen. Für interne API-Endpunkte, die von der Weboberfläche verwendet werden, werden Änderungen automatisch verarbeitet und erfordern keine manuellen Aktualisierungen.

Hinweis

Externe API-Endpunkte werden zur Gewährleistung der Rückwärtskompatibilität nach Möglichkeit beibehalten. Breaking Changes werden nur eingeführt, wenn dies für Konsistenz, Sicherheit oder Funktionsverbesserungen erforderlich ist.

Versionsspezifische Änderungen

Version 1.3.0

Keine Breaking Changes für externe API-Endpunkte

Version 1.2.1

Keine Breaking Changes für externe API-Endpunkte

Version 1.1.x

Keine Breaking Changes für externe API-Endpunkte

Version 1.0.x

Keine Breaking Changes für externe API-Endpunkte

Version 0.9.x

Keine Breaking Changes für externe API-Endpunkte

Version 0.9.x führt Authentifizierung ein und erfordert, dass sich alle Benutzer anmelden. Beim Upgrade von Version 0.8.x:

Authentifizierung erforderlich: Alle Seiten und internen API-Endpunkte erfordern jetzt Authentifizierung
Standard-Admin-Konto: Ein Standard-Admin-Konto wird automatisch erstellt:
- Benutzername: admin
- Passwort: Duplistatus09 (muss beim ersten Anmelden geändert werden)
Sitzungsentwertung: Alle bestehenden Sitzungen werden entwertet
Externer API-Zugriff: Externe API-Endpunkte (/api/summary, /api/lastbackup, /api/lastbackups, /api/upload) bleiben unauthentifiziert für Kompatibilität mit Integrationen und Duplicati

Version 0.8.x

Keine Breaking Changes für externe API-Endpunkte

Version 0.8.x führt keine Breaking Changes für externe API-Endpunkte ein. Die folgenden Endpunkte bleiben unverändert:

/api/summary - Antwortstruktur unverändert
/api/lastbackup/{serverId} - Antwortstruktur unverändert
/api/lastbackups/{serverId} - Antwortstruktur unverändert
/api/upload - Anfrage-/Antwortformat unverändert

Sicherheitsverbesserungen

Obwohl keine Breaking Changes an externen API-Endpunkten vorgenommen wurden, enthält Version 0.8.x Sicherheitsverbesserungen:

CSRF-Schutz: CSRF-Token-Validierung wird für zustandsändernde API-Anfragen erzwungen, externe APIs bleiben jedoch kompatibel
Passwort-Sicherheit: Passwort-Endpunkte sind aus Sicherheitsgründen auf die Benutzeroberfläche beschränkt

Hinweis

Diese Sicherheitsverbesserungen beeinflussen nicht die externen API-Endpunkte, die zum Lesen von Sicherungsdaten verwendet werden. Falls Sie benutzerdefinierte Skripte mit internen Endpunkten verwenden, können diese eine CSRF-Token-Behandlung erfordern.

Version 0.7.x

Version 0.7.x führt mehrere Breaking Changes bei externen API-Endpunkten ein, die Aktualisierungen an externen Integrationen erfordern.

Brechende Änderungen

Feldumbenennung

totalMachines → totalServers im /api/summary Endpunkt
machine → server in API-Antwortobjekten
backup_types_count → backup_jobs_count im /api/lastbackups/{serverId} Endpunkt

Änderungen an Endpunkt-Pfaden

Alle API-Endpunkte, die zuvor /api/machines/... verwendeten, verwenden jetzt /api/servers/...
Parameternamen wurden von machine_id zu server_id geändert (URL-Codierung funktioniert weiterhin mit beiden)

Änderungen der Antwortstruktur

Die Antwortstruktur für mehrere Endpunkte wurde zur Konsistenz aktualisiert:

`/api/summary`

Vorher (0.6.x und früher):

{
  "totalMachines": 3,
  "totalBackupsRuns": 9,
  "totalBackups": 9,
  "totalUploadedSize": 2397229507,
  "totalStorageUsed": 43346796938,
  "totalBackupSize": 126089687807,
  "overdueBackupsCount": 2,
  "secondsSinceLastBackup": 7200
}

Nach (0.7.x+):

{
  "totalServers": 3,  // Changed from "totalMachines"
  "totalBackupsRuns": 9,
  "totalBackups": 9,
  "totalUploadedSize": 2397229507,
  "totalStorageUsed": 43346796938,
  "totalBackupSize": 126089687807,
  "overdueBackupsCount": 2,
  "secondsSinceLastBackup": 7200
}

`/api/lastbackup/{serverId}`

Vorher (0.6.x und früher):

{
  "machine": {  // Changed to "server"
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Backup Name",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backup": {
    // ... backup details
  },
  "status": 200
}

Nach (0.7.x+):

{
  "server": {  // Changed from "machine"
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Backup Name",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backup": {
    // ... backup details
  },
  "status": 200
}

`/api/lastbackups/{serverId}`

Vorher (0.6.x und früher):

{
  "machine": {  // Changed to "server"
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Default Backup",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backups": [
    // ... backup array
  ],
  "backup_types_count": 2,  // Changed to "backup_jobs_count"
  "backup_names": ["Files", "Databases"],
  "status": 200
}

Nach (0.7.x+):

{
  "server": {  // Changed from "machine"
    "id": "unique-server-id",
    "name": "Server Name",
    "backup_name": "Default Backup",
    "backup_id": "backup-id",
    "created_at": "2024-03-20T10:00:00Z"
  },
  "latest_backups": [
    // ... backup array
  ],
  "backup_jobs_count": 2,  // Changed from "backup_types_count"
  "backup_names": ["Files", "Databases"],
  "status": 200
}

Migrationsschritte

Wenn Sie von einer Version vor 0.7.x aktualisieren, führen Sie diese Schritte aus:

Feldverweise aktualisieren: Ersetzen Sie alle Verweise auf alte Feldnamen durch neue
- totalMachines → totalServers
- backup_types_count → backup_jobs_count
Objektschlüssel aktualisieren: Ändern Sie machine in server bei der Antwortanalyse
- Aktualisieren Sie jeden Code, der auf response.machine zugreift, zu response.server
Endpunkt-Pfade aktualisieren: Ändern Sie alle Endpunkte, die /api/machines/... verwenden, in /api/servers/...
- Hinweis: Parameter können weiterhin alte Bezeichner akzeptieren; Pfade sollten aktualisiert werden
Testintegration: Bestätigen Sie, dass Ihre Integration mit der neuen API-Struktur funktioniert
- Testen Sie alle Endpunkte, die Ihre Anwendung verwendet
- Bestätigen Sie, dass die Antwortanalyse neue Feldnamen korrekt verarbeitet
Dokumentation aktualisieren: Aktualisieren Sie alle internen Dokumentationen, die auf die alte API verweisen
- Aktualisieren Sie API-Beispiele und Feldnamenreferenzen

Kompatibilität

Rückwärtskompatibilität

Version 1.2.1: Vollständig abwärtskompatibel mit der API-Struktur von 1.1.x
Version 1.1.x: Vollständig abwärtskompatibel mit der API-Struktur von 1.0.x
Version 1.0.x: Vollständig abwärtskompatibel mit der API-Struktur von 0.9.x
Version 0.9.x: Vollständig abwärtskompatibel mit der API-Struktur von 0.8.x
Version 0.8.x: Vollständig abwärtskompatibel mit der API-Struktur von 0.7.x
Version 0.7.x: Nicht abwärtskompatibel mit Versionen vor 0.7.x
- Alte Feldnamen funktionieren nicht
- Alte Endpunkt-Pfade funktionieren nicht

Zukünftige Unterstützung

Alte Feldnamen aus Versionen vor 0.7.x sind nicht unterstützt
Alte Endpunkt-Pfade aus Versionen vor 0.7.x sind nicht unterstützt
Zukünftige Versionen werden die aktuelle API-Struktur beibehalten, sofern keine Breaking Changes erforderlich sind

Zusammenfassung der externen API-Endpunkte

Die folgenden externen API-Endpunkte werden aus Gründen der Abwärtskompatibilität beibehalten und bleiben unauthentifiziert:

Endpoint	Method	Beschreibung	Breaking Changes
`/api/summary`	GET	Gesamtübersicht von Sicherungsvorgängen	0.7.x: `totalMachines` → `totalServers`
`/api/lastbackup/{serverId}`	GET	Neueste Sicherung für einen Server	0.7.x: `machine` → `server`
`/api/lastbackups/{serverId}`	GET	Neueste Sicherungen für alle Sicherungsaufträge	0.7.x: `machine` → `server`, `backup_types_count` → `backup_jobs_count`
`/api/upload`	POST	Hochladen von Sicherungsdaten von Duplicati	Nein Breaking Changes

Hilfe?

Wenn Sie Hilfe beim Aktualisieren Ihrer Integration benötigen:

API Reference: Prüfen Sie die API Reference für aktuelle Endpoint-Dokumentation
External APIs: Siehe External APIs für detaillierte Endpoint-Dokumentation
Migration Guide: Lesen Sie das Migration Guide für allgemeine Migrationsinformationen
Release Notes: Lesen Sie versionsspezifische Release Notes für zusätzlichen Kontext
Support: Öffnen Sie ein Issue auf GitHub für Support

Übersicht
Versionsspezifische Änderungen
Migrationsschritte
Kompatibilität
- Rückwärtskompatibilität
- Zukünftige Unterstützung
Zusammenfassung der externen API-Endpunkte
Hilfe?