185 lines
3.7 KiB
Markdown
185 lines
3.7 KiB
Markdown
# 03 — API Reference
|
|
|
|
## Conventions
|
|
|
|
- All endpoints under `/api/`.
|
|
- Request bodies: `application/json` or `multipart/form-data` where noted.
|
|
- Responses: `application/json` unless file download.
|
|
- Export filenames follow pattern: `YYYY-MM-DD (SERVER MODEL) - SERVER SN.<ext>`
|
|
|
|
---
|
|
|
|
## Upload & Data Input
|
|
|
|
### `POST /api/upload`
|
|
|
|
Upload a vendor diagnostic archive or a JSON snapshot.
|
|
|
|
**Request:** `multipart/form-data`, field name `archive`.
|
|
Server-side multipart limit: **100 MiB**.
|
|
|
|
Accepted inputs:
|
|
- `.tar`, `.tar.gz`, `.tgz` — vendor diagnostic archives
|
|
- `.txt` — plain text files
|
|
- JSON file containing a serialized `AnalysisResult` — re-loaded as-is
|
|
|
|
**Response:** `200 OK` with parsed result summary, or `4xx`/`5xx` on error.
|
|
|
|
---
|
|
|
|
## Live Collection
|
|
|
|
### `POST /api/collect`
|
|
|
|
Start a live collection job (`redfish` or `ipmi`).
|
|
|
|
**Request body:**
|
|
```json
|
|
{
|
|
"host": "bmc01.example.local",
|
|
"protocol": "redfish",
|
|
"port": 443,
|
|
"username": "admin",
|
|
"auth_type": "password",
|
|
"password": "secret",
|
|
"tls_mode": "insecure"
|
|
}
|
|
```
|
|
|
|
Supported values:
|
|
- `protocol`: `redfish` | `ipmi`
|
|
- `auth_type`: `password` | `token`
|
|
- `tls_mode`: `strict` | `insecure`
|
|
|
|
**Response:** `202 Accepted`
|
|
```json
|
|
{
|
|
"job_id": "job_a1b2c3d4e5f6",
|
|
"status": "queued",
|
|
"message": "Collection job accepted",
|
|
"created_at": "2026-02-23T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
Validation behavior:
|
|
- `400 Bad Request` for invalid JSON
|
|
- `422 Unprocessable Entity` for semantic validation errors (missing/invalid fields)
|
|
|
|
### `GET /api/collect/{id}`
|
|
|
|
Poll job status and progress log.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"job_id": "job_a1b2c3d4e5f6",
|
|
"status": "running",
|
|
"progress": 55,
|
|
"logs": ["..."],
|
|
"created_at": "2026-02-23T12:00:00Z",
|
|
"updated_at": "2026-02-23T12:00:10Z"
|
|
}
|
|
```
|
|
|
|
Status values: `queued` | `running` | `success` | `failed` | `canceled`
|
|
|
|
### `POST /api/collect/{id}/cancel`
|
|
|
|
Cancel a running job.
|
|
|
|
---
|
|
|
|
## Data Queries
|
|
|
|
### `GET /api/status`
|
|
|
|
Returns source metadata for the current dataset.
|
|
|
|
```json
|
|
{
|
|
"loaded": true,
|
|
"filename": "redfish://bmc01.example.local",
|
|
"vendor": "redfish",
|
|
"source_type": "api",
|
|
"protocol": "redfish",
|
|
"target_host": "bmc01.example.local",
|
|
"collected_at": "2026-02-10T15:30:00Z",
|
|
"stats": { "events": 0, "sensors": 0, "fru": 0 }
|
|
}
|
|
```
|
|
|
|
`source_type`: `archive` | `api`
|
|
|
|
When no dataset is loaded, response is `{ "loaded": false }`.
|
|
|
|
### `GET /api/config`
|
|
|
|
Returns source metadata plus:
|
|
- `hardware.board`
|
|
- `hardware.firmware`
|
|
- canonical `hardware.devices`
|
|
- computed `specification` summary lines
|
|
|
|
### `GET /api/events`
|
|
|
|
Returns parsed diagnostic events.
|
|
|
|
### `GET /api/sensors`
|
|
|
|
Returns sensor readings (temperatures, voltages, fan speeds).
|
|
|
|
### `GET /api/serials`
|
|
|
|
Returns serial numbers built from canonical `hardware.devices`.
|
|
|
|
### `GET /api/firmware`
|
|
|
|
Returns firmware versions built from canonical `hardware.devices`.
|
|
|
|
### `GET /api/parsers`
|
|
|
|
Returns list of registered vendor parsers with their identifiers.
|
|
|
|
---
|
|
|
|
## Export
|
|
|
|
### `GET /api/export/csv`
|
|
|
|
Download serial numbers as CSV.
|
|
|
|
### `GET /api/export/json`
|
|
|
|
Download full `AnalysisResult` as JSON (includes `raw_payloads`).
|
|
|
|
### `GET /api/export/reanimator`
|
|
|
|
Download hardware data in Reanimator format for asset tracking integration.
|
|
See [`07-exporters.md`](07-exporters.md) for full format spec.
|
|
|
|
---
|
|
|
|
## Management
|
|
|
|
### `DELETE /api/clear`
|
|
|
|
Clear current in-memory dataset.
|
|
|
|
### `POST /api/shutdown`
|
|
|
|
Gracefully shut down the server process.
|
|
This endpoint terminates the current process after responding.
|
|
|
|
---
|
|
|
|
## Source metadata fields
|
|
|
|
Fields present in `/api/status` and `/api/config`:
|
|
|
|
| Field | Values |
|
|
|-------|--------|
|
|
| `source_type` | `archive` \| `api` |
|
|
| `protocol` | `redfish` \| `ipmi` (may be empty for archive uploads) |
|
|
| `target_host` | IP or hostname |
|
|
| `collected_at` | RFC3339 timestamp |
|