Ir al contenido principal

Cambios de API incompatibles con versiones anteriores

Este documento describe los cambios disruptivos en los puntos finales de la API externa en diferentes versiones de duplistatus. Los puntos finales de la API externa son aquellos diseñados para ser utilizados por otras aplicaciones e integraciones (por ejemplo, integración de Homepage).

Resumen

Este documento cubre cambios disruptivos en los puntos finales de API externos que afectan a las integraciones, scripts y aplicaciones que consumen estos puntos finales. Para los puntos finales de API internos utilizados por la interfaz web, los cambios se manejan automáticamente y no requieren actualizaciones manuales.

nota

Los puntos finales de API externos se mantienen para compatibilidad hacia atrás cuando es posible. Los cambios disruptivos solo se introducen cuando es necesario para mejoras de consistencia, seguridad o funcionalidad.

Cambios Específicos de Versión

Versión 1.3.0

Sin cambios disruptivos en los puntos finales de la API externa

Versión 1.2.1

Sin cambios disruptivos en los puntos finales de la API externa

Versión 1.1.x

Sin cambios disruptivos en los puntos finales de la API externa

Versión 1.0.x

Sin cambios disruptivos en los puntos finales de la API externa

Versión 0.9.x

Sin cambios disruptivos en los puntos finales de la API externa

La versión 0.9.x introduce autenticación y requiere que todos los usuarios inicien sesión. Al actualizar desde la versión 0.8.x:

Autenticación requerida: Todas las páginas y puntos finales de API internos ahora requieren autenticación
Cuenta Admin por defecto: Una cuenta admin por defecto se crea automáticamente:
- Nombre de usuario: admin
- Contraseña: Duplistatus09 (debe cambiarse al iniciar sesión por primera vez)
Invalidación de sesiones: Todas las sesiones existentes se invalidan
Acceso a API externa: Los puntos finales de API externa (/api/summary, /api/lastbackup, /api/lastbackups, /api/upload) permanecen sin autenticación para compatibilidad con integraciones y Duplicati

Versión 0.8.x

Sin cambios disruptivos en los puntos finales de la API externa

Versión 0.8.x no introduce cambios disruptivos en los puntos finales de API externos. Los siguientes puntos finales permanecen sin cambios:

/api/summary - Estructura de respuesta sin cambios
/api/lastbackup/{serverId} - Estructura de respuesta sin cambios
/api/lastbackups/{serverId} - Estructura de respuesta sin cambios
/api/upload - Formato de solicitud/respuesta sin cambios

Mejoras de Seguridad

Aunque no se realizaron cambios importantes en los puntos finales de la API externa, la versión 0.8.x incluye mejoras de seguridad:

Protección CSRF: La validación de token CSRF se aplica para solicitudes de API que cambian estado, pero las API externas siguen siendo compatibles
Seguridad de Contraseña: Los puntos finales de contraseña están restringidos a la interfaz de usuario por razones de seguridad

nota

Estas mejoras de seguridad no afectan los puntos finales de API externos utilizados para leer datos de backup. Si tiene scripts personalizados que utilizan puntos finales internos, es posible que requieran manejo de tokens CSRF.

Versión 0.7.x

La versión 0.7.x introduce varios cambios disruptivos en los puntos finales de la API externa que requieren actualizaciones en las integraciones externas.

Cambios Importantes

Cambio de Nombre de Campo

totalMachines → totalServers en el endpoint /api/summary
machine → server en objetos de respuesta de API
backup_types_count → backup_jobs_count en el endpoint /api/lastbackups/{serverId}

Cambios en la Ruta del Endpoint

Todos los puntos finales de API que anteriormente utilizaban /api/machines/... ahora utilizan /api/servers/...
Los nombres de parámetros cambiaron de machine_id a server_id (la codificación de URL sigue funcionando con ambos)

Cambios en la Estructura de Respuesta

La estructura de respuesta para varios endpoints ha sido actualizada por consistencia:

`/api/summary`

Antes (0.6.x y anteriores):

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

Después (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}`

Antes (0.6.x y anteriores):

{
  "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
}

Después (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}`

Antes (0.6.x y anteriores):

{
  "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
}

Después (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
}

Pasos de Migración

Si está actualizando desde una versión anterior a 0.7.x, siga estos pasos:

Actualizar Referencias de Campo: Reemplaza todas las referencias a nombres de campo antiguos con los nuevos
- totalMachines → totalServers
- backup_types_count → backup_jobs_count
Actualizar Claves de Objeto: Cambiar machine a server en el análisis de respuestas
- Actualizar cualquier código que acceda a response.machine a response.server
Actualizar Rutas de Endpoints: Cambiar cualquier endpoint que use /api/machines/... a /api/servers/...
- Nota: Los parámetros aún pueden aceptar identificadores antiguos; las rutas deben actualizarse
Integración de Pruebas: Verificar que su integración funciona con la nueva estructura de API
- Probar todos los puntos finales que utiliza su aplicación
- Verificar que el análisis de respuestas maneja correctamente los nuevos nombres de campos
Actualizar Documentación: Actualizar cualquier documentación interna que haga referencia a la API antigua
- Actualizar ejemplos de API y referencias de nombres de campos

Compatibilidad

Compatibilidad hacia atrás

Versión 1.2.1: Totalmente compatible hacia atrás con la estructura de API 1.1.x
Versión 1.1.x: Totalmente compatible hacia atrás con la estructura de API 1.0.x
Versión 1.0.x: Totalmente compatible hacia atrás con la estructura de API 0.9.x
Versión 0.9.x: Totalmente compatible hacia atrás con la estructura de API 0.8.x
Versión 0.8.x: Totalmente compatible hacia atrás con la estructura de API 0.7.x
Versión 0.7.x: No es compatible hacia atrás con versiones anteriores a 0.7.x
- Los nombres de campo antiguos no funcionarán
- Las rutas de extremo antiguas no funcionarán

Soporte Futuro

Los nombres de campo antiguos de versiones anteriores a 0.7.x no son compatibles
Las rutas de punto de conexión antiguas de versiones anteriores a 0.7.x no son compatibles
Las versiones futuras mantendrán la estructura de API actual a menos que sean necesarios cambios importantes

Resumen de Puntos Finales de API Externos

Los siguientes puntos finales de API externos se mantienen por compatibilidad con versiones anteriores y permanecen sin autenticación:

Endpoint	Método	Descripción	Cambios Incompatibles
`/api/summary`	GET	Resumen general de operaciones de backup	0.7.x: `totalMachines` → `totalServers`
`/api/lastbackup/{serverId}`	GET	Último backup para un servidor	0.7.x: `machine` → `server`
`/api/lastbackups/{serverId}`	GET	Últimos backups para todos los trabajos de backup	0.7.x: `machine` → `server`, `backup_types_count` → `backup_jobs_count`
`/api/upload`	POST	Subir datos de backup desde Duplicati	No hay cambios incompatibles

¿Necesita ayuda?

Si necesita asistencia para actualizar su integración:

Referencia de API: Verifique la Referencia de API para la documentación actual de puntos finales
APIs Externas: Consulte APIs Externas para documentación detallada de puntos finales
Guía de Migración: Revise la Guía de Migración para información general de migración
Notas de la Versión: Revise las Notas de la Versión específicas de la versión para contexto adicional
Soporte: Abra un problema en GitHub para obtener soporte

Resumen
Cambios Específicos de Versión
Pasos de Migración
Compatibilidad
- Compatibilidad hacia atrás
- Soporte Futuro
Resumen de Puntos Finales de API Externos
¿Necesita ayuda?