Pular para o conteúdo principal

Mudanças de API incompatíveis com versões anteriores

Este documento descreve mudanças significativas nos endpoints da API externa em diferentes versões do duplistatus. Os endpoints da API externa são aqueles projetados para uso por outros aplicativos e integrações (por exemplo, integração da Homepage).

Visão geral

Este documento aborda as mudanças significativas nos endpoints de API externa que afetam integrações, scripts e aplicações que consomem esses endpoints. Para endpoints de API interna usados pela interface web, as mudanças são tratadas automaticamente e não exigem atualizações manuais.

nota

Os endpoints de API externa são mantidos para compatibilidade com versões anteriores quando possível. As mudanças significativas são introduzidas apenas quando necessário para melhorias de consistência, segurança ou funcionalidade.

Alterações Específicas da Versão

Versão 1.3.0

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 1.2.1

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 1.1.x

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 1.0.x

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 0.9.x

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 0.9.x introduz autenticação e requer que todos os usuários façam login. Quando atualizar da versão 0.8.x:

Autenticação Necessária: Todas as páginas e endpoints da API interna agora exigem autenticação
Conta de Administrador Padrão: Uma conta de administrador padrão é criada automaticamente:
- Nome de usuário: admin
- Senha: Duplistatus09 (deve ser alterada no primeiro login)
Invalidação de Sessão: Todas as sessões existentes são invalidadas
Acesso à API Externa: Os endpoints da API externa (/api/summary, /api/lastbackup, /api/lastbackups, /api/upload) permanecem sem autenticação para compatibilidade com integrações e Duplicati

Versão 0.8.x

Nenhuma Mudança Significativa nos Endpoints de API Externa

Versão 0.8.x não introduz nenhuma alteração significativa nos endpoints da API externa. Os seguintes endpoints permanecem inalterados:

/api/summary - Estrutura de resposta inalterada
/api/lastbackup/{serverId} - Estrutura de resposta inalterada
/api/lastbackups/{serverId} - Estrutura de resposta inalterada
/api/upload - Formato de solicitação/resposta inalterado

Melhorias de Segurança

Embora nenhuma alteração significativa tenha sido feita nos endpoints da API externa, a Versão 0.8.x inclui melhorias de segurança:

Proteção CSRF: A validação do token CSRF é aplicada para solicitações de API que alteram o estado, mas as APIs externas permanecem compatíveis.
Segurança da Senha: Os endpoints de senha são restritos à interface do usuário por razões de segurança.

nota

Esses aprimoramentos de segurança não afetam os endpoints de API externos usados para ler dados de backup. Se você tiver scripts personalizados usando endpoints internos, eles podem exigir tratamento de token CSRF.

Versão 0.7.x

A Versão 0.7.x introduz várias mudanças significativas nos endpoints da API externa que exigem atualizações nas Integrações externas.

Alterações Significativas

Renomeação de Campos

totalMachines → totalServers no endpoint /api/summary
machine → server em objetos de resposta de API
backup_types_count → backup_jobs_count no endpoint /api/lastbackups/{serverId}

Alterações no Caminho do Endpoint

Todos os endpoints de API que usavam /api/machines/... agora usam /api/servers/...
Nomes de parâmetros alterados de machine_id para server_id (a codificação de URL ainda funciona com ambos)

Alterações na Estrutura de Resposta

A estrutura de resposta para vários endpoints foi atualizada para consistência:

`/api/summary`

Antes (0.6.x e anteriores):

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

Depois (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 e 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
}

Depois (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 e 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
}

Depois (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
}

Etapas de Migração

Se você está atualizando de uma versão anterior a 0.7.x, siga estas etapas:

Atualizar Referências de Campo: Substitua todas as referências aos nomes de campo antigos pelos novos
- totalMachines → totalServers
- backup_types_count → backup_jobs_count
Atualizar Chaves de Objeto: Altere machine para server na análise de resposta
- Atualize qualquer código que acesse response.machine para response.server
Atualizar Caminhos de Endpoint: Altere qualquer endpoint usando /api/machines/... para /api/servers/...
- Nota: Os parâmetros ainda podem aceitar identificadores antigos; os caminhos devem ser atualizados
Testar Integração: Verifique se sua integração funciona com a nova estrutura de API
- Teste todos os endpoints que sua aplicação usa
- Verifique se a análise de resposta trata corretamente os novos nomes de campo
Atualizar Documentação: Atualize qualquer documentação interna que faça referência à API antiga
- Atualize exemplos de API e referências de nomes de campo

Compatibilidade

Compatibilidade com Versões Anteriores

Versão 1.2.1: Totalmente compatível com a estrutura de API 1.1.x
Versão 1.1.x: Totalmente compatível com a estrutura de API 1.0.x
Versão 1.0.x: Totalmente compatível com a estrutura de API 0.9.x
Versão 0.9.x: Totalmente compatível com a estrutura de API 0.8.x
Versão 0.8.x: Totalmente compatível com a estrutura de API 0.7.x
Versão 0.7.x: Não é compatível com versões anteriores a 0.7.x
- Nomes de campo antigos não funcionarão
- Caminhos de endpoint antigos não funcionarão

Suporte Futuro

Nomes de campo antigos de versões anteriores a 0.7.x não são suportados
Caminhos de endpoint antigos de versões anteriores a 0.7.x não são suportados
Versões futuras manterão a estrutura de API atual, a menos que mudanças significativas sejam necessárias

Resumo dos Endpoints de API Externa

Os seguintes endpoints de API externa são mantidos para compatibilidade com versões anteriores e permanecem não autenticados:

Endpoint	Método	Descrição	Mudanças Significativas
`/api/summary`	GET	Resumo geral das operações de backup	0.7.x: `totalMachines` → `totalServers`
`/api/lastbackup/{serverId}`	GET	Backup mais recente para um servidor	0.7.x: `machine` → `server`
`/api/lastbackups/{serverId}`	GET	Backups mais recentes para todos os trabalhos de backup	0.7.x: `machine` → `server`, `backup_types_count` → `backup_jobs_count`
`/api/upload`	POST	Carregar dados de backup do Duplicati	Sem alterações significativas

Precisa de Ajuda?

Se você precisar de assistência para atualizar sua integração:

Referência da API: Verifique a Referência da API para documentação de endpoints atual
APIs externas: Consulte APIs externas para documentação detalhada de endpoints
Guia de Migração: Revise o Guia de Migração para informações gerais de migração
Notas de Versão: Revise as Notas de Versão específicas da versão para contexto adicional
Suporte: Abra uma issue no GitHub para obter suporte

Visão geral
Alterações Específicas da Versão
Etapas de Migração
Compatibilidade
- Compatibilidade com Versões Anteriores
- Suporte Futuro
Resumo dos Endpoints de API Externa
Precisa de Ajuda?