onever_drive/docs/api_reference.md

OnEver Drive — Referencia de API REST & WebSockets

Base URL: /api

---

1. Autenticación

POST /api/auth/login

Inicia sesión de usuario administrativo.

• Body:

  {
    "email": "admin@oneverdrive.local",
    "password": "Admin1234!"
  }
  

• Response:

  {
    "access_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "user": { "id": 1, "email": "admin@oneverdrive.local", "role": "ADMIN" }
  }
  

---

2. Clientes Windows

POST /api/clients/registration-code

Genera un código temporal de un solo uso para registrar un nuevo agente Windows.

• Auth: Bearer Token (ADMIN)
• Body: { "client_name_hint": "SQL Server Prod", "expires_in_hours": 48 }
• Response: { "code": "OED-4A2F-9B1C", "expires_at": "2026-08-15T12:00:00Z" }

POST /api/clients/register

Invocado por el agente Windows con el código de registro para obtener credenciales únicas.

• Body:

  {
    "registration_code": "OED-4A2F-9B1C",
    "name": "SQL Server Prod",
    "hostname": "WIN-SRV-2022",
    "os_info": "Windows Server 2022 Datacenter",
    "agent_version": "1.0.0"
  }
  

• Response:

  {
    "client_code": "CLIENT-0001",
    "device_id": "8f3b4d7c-3b1a-4d2e-9c1a-8f3b4d7c3b1a",
    "device_token": "oed_sec_a8b9c0d1...",
    "name": "SQL Server Prod",
    "server_time": "2026-08-13T16:00:00Z"
  }
  

GET /api/clients

Lista todos los clientes registrados.

POST /api/clients/{id}/revoke

Revoca inmediatamente las credenciales de un cliente Windows.

---

3. Motor de Transferencia por Chunks

POST /api/upload/session

Inicia una nueva sesión de subida o reanuda una sesión existente incompleta.

• Headers: X-Device-Id: <DEVICE_ID> X-Device-Token: <DEVICE_TOKEN>
• Body:

  {
    "filename": "database_production.bak",
    "file_size": 12582912,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "chunk_size": 4194304,
    "job_id": 1
  }
  

• Response:

  {
    "session_code": "6f2e8b1a-...",
    "filename": "database_production.bak",
    "file_size": 12582912,
    "chunk_size": 4194304,
    "total_chunks": 3,
    "received_chunks": [0],
    "status": "UPLOADING"
  }
  

POST /api/upload/{session_code}/chunk

Envía los bytes de un bloque específico.

• Headers: X-Device-Id: <DEVICE_ID> X-Device-Token: <DEVICE_TOKEN> X-Chunk-Index: 1 X-Chunk-SHA256: <CHUNK_HASH>
• Body: Raw binary bytes
• Response:

  {
    "chunk_index": 1,
    "is_received": true,
    "total_received": 2,
    "total_chunks": 3,
    "progress_percent": 66.67
  }
  

GET /api/upload/{session_code}/status

Devuelve el estado de la sesión y la lista de chunks pendientes de subida.

POST /api/upload/{session_code}/complete

Solicita el ensamblado secuencial del archivo y la verificación de integridad SHA-256 total.

• Response:

  {
    "session_code": "6f2e8b1a-...",
    "filename": "database_production.bak",
    "relative_path": "clients/CLIENT-0001/JOB-001/20260813_160000_database_production.bak",
    "file_size": 12582912,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "status": "SUCCESS"
  }
  

---

4. WebSockets Telemetría en Tiempo Real

Endpoint: /ws/telemetry

Eventos transmitidos:

• UPLOAD_PROGRESS: { "session_code", "filename", "client_id", "chunk_index", "received_chunks", "total_chunks", "progress_percent" }
• UPLOAD_COMPLETED: { "session_code", "filename", "client_id", "file_size", "sha256", "status" }
• CLIENT_REGISTERED: { "id", "client_code", "name", "hostname", "status" }
• EVENT_LOG: { "id", "timestamp", "event_type", "severity", "message" }