144 lines
3.7 KiB
Markdown
144 lines
3.7 KiB
Markdown
# OnEver Drive — Referencia de API REST & WebSockets
|
|
|
|
Base URL: `/api`
|
|
|
|
---
|
|
|
|
## 1. Autenticación
|
|
|
|
### `POST /api/auth/login`
|
|
Inicia sesión de usuario administrativo.
|
|
- **Body**:
|
|
```json
|
|
{
|
|
"email": "admin@oneverdrive.local",
|
|
"password": "Admin1234!"
|
|
}
|
|
```
|
|
- **Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"filename": "database_production.bak",
|
|
"file_size": 12582912,
|
|
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
|
|
"chunk_size": 4194304,
|
|
"job_id": 1
|
|
}
|
|
```
|
|
- **Response**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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" }`
|