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 la API interna ahora requieren autenticación
Cuenta de administrador por defecto: Se crea automáticamente una cuenta de administrador por defecto:
- Nombre de usuario: admin
- Contraseña: Duplistatus09 (debe cambiarse en el primer inicio de sesión)
Invalidación de sesiones: Todas las sesiones existentes se invalidan
Acceso a la API externa: Los puntos finales de la API externa (/api/summary, /api/lastbackup, /api/lastbackups, /api/upload) permanecen sin autenticar para mantener 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 punto final /api/summary
machine → server en los objetos de respuesta de la API
backup_types_count → backup_jobs_count en el punto final /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 con la estructura de API 1.1.x
Versión 1.1.x: Totalmente compatible con la estructura de API 1.0.x
Versión 1.0.x: Totalmente compatible con la estructura de API 0.9.x
Versión 0.9.x: Totalmente compatible con la estructura de API 0.8.x
Versión 0.8.x: Totalmente compatible con la estructura de API 0.7.x
Versión 0.7.x: No es compatible con versiones anteriores a 0.7.x
- Los nombres antiguos de campos no funcionarán
- Las rutas antiguas de puntos finales 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:

Punto final	Método	Descripción	Cambios importantes
`/api/summary`	GET	Resumen general de las operaciones de copia de seguridad	0.7.x: `totalMachines` → `totalServers`
`/api/lastbackup/{serverId}`	GET	Última copia de seguridad para un servidor	0.7.x: `machine` → `server`
`/api/lastbackups/{serverId}`	GET	Últimas copias de seguridad para todos los trabajos de copia de seguridad	0.7.x: `machine` → `server`, `backup_types_count` → `backup_jobs_count`
`/api/upload`	POST	Cargar datos de copia de seguridad desde Duplicati	Sin cambios importantes

¿Necesita ayuda?

Si necesita asistencia para actualizar su integración:

Referencia de API: Verifique la Referencia de API para documentación actualizada 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 sobre migración
Notas de versión: Revise las Notas de versión específicas de cada versión para obtener contexto adicional
Soporte: Abra un problema en GitHub para obtener ayuda

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?