API REST

La Consola Web de NGBackup expone una API REST versionada bajo /api/v1/. Todo lo que hace la interfaz de la consola — ejecutar jobs, navegar puntos de restauración, leer el estado de salud — está disponible para clientes de máquina por los mismos endpoints.

El documento OpenAPI

La API se describe a sí misma. Obtenga el documento OpenAPI 3.1 generado desde una Consola Web en ejecución (autenticado, como todo endpoint):

curl -H "Authorization: Bearer $NGB_TOKEN" \
  https://console.example.com/api/v1/openapi.json

El documento se genera a partir de las anotaciones de los propios handlers del servidor en tiempo de compilación, por lo que no puede divergir de las rutas que describe. Cobertura actual: tokens, auth, operations, restore, directors, storage-media, stats. Los grupos aún internos (pipeline de configuración, admin, plugins, reportes, automatización, advanced) se agregan a medida que se estabilizan — trate cualquier endpoint ausente del documento como sujeto a cambios sin aviso.

Autenticación: tokens de API personales

Los usuarios interactivos inician sesión con una cookie; los clientes de máquina usan tokens de API personales — credenciales bearer con el rol del usuario emisor congelado al momento de la creación.

Cree uno desde la interfaz (Seguridad → Tokens de API) o por la API usando una sesión de navegador:

# Devuelve el resumen del token más "plaintext" — mostrado UNA sola vez.
curl -X POST https://console.example.com/api/v1/tokens \
  -H "Cookie: backupweb_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "terraform-prod"}'

Guarde el valor plaintext (ngbt_…) — el servidor conserva solo su SHA-256. Luego autentique cualquier solicitud con él:

curl -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/operations/jobs

Los tokens actúan con el rol bajo el cual fueron creados (admin, operator, readonly o un rol de capacidades personalizado). Revoque en cualquier momento — la revocación es inmediata y la fila se conserva como rastro de auditoría:

curl -X DELETE -H "Authorization: Bearer ngbt_…" \
  https://console.example.com/api/v1/tokens/<id>

La creación y la revocación quedan auditadas (api_token.create / api_token.revoke).

Tour rápido

AUTH='Authorization: Bearer ngbt_…'
BASE=https://console.example.com/api/v1

# Salud consolidada del Director
curl -H "$AUTH" $BASE/director/health

# Jobs recientes
curl -H "$AUTH" $BASE/operations/jobs/recent

# Ejecutar un job
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"job": "BackupWebServer", "level": "Incremental"}' \
  $BASE/operations/jobs/run

# Buscar un archivo en el catálogo a través de la cadena de restauración
curl -H "$AUTH" "$BASE/restore/bvfs/search?jobids=101,102&q=config.ini"

Los esquemas de solicitud y respuesta de cada endpoint cubierto, incluidos códigos de estado y tipos de parámetros, están en el documento OpenAPI de arriba — apunte cualquier cliente compatible con OpenAPI (Swagger UI, Postman, openapi-generator) hacia él.

Eventos de alerta para integraciones

Los canales de notificación (correo/webhook, Administración → Notificaciones) se suscriben a patrones de eventos. Acciones relevantes para máquinas:

Acción	Se dispara cuando
`job.completed.error` / `job.completed.warning`	un job termina mal
`client.silence.warn` / `client.silence.crit`	un cliente lleva más tiempo sin un backup exitoso que el umbral warn/crit
`client.silence.ok`	un cliente antes silencioso se recupera
`api_token.create` / `api_token.revoke`	ciclo de vida de tokens (auditoría)

Los umbrales son configurables por el operador (Administración → Monitoreo); los canales webhook pueden apuntar a URLs de ingestión estilo PagerDuty/OpsGenie.