200 lines
4.6 KiB
Markdown
200 lines
4.6 KiB
Markdown
# 03 — API Reference
|
|
|
|
## Conventions
|
|
|
|
- All endpoints are under `/api/`
|
|
- JSON responses are used unless the endpoint downloads a file
|
|
- Async jobs share the same status model: `queued`, `running`, `success`, `failed`, `canceled`
|
|
- Export filenames use `YYYY-MM-DD (MODEL) - SERIAL.<ext>` when board metadata exists
|
|
- Embedded chart viewer routes live under `/chart/` and return HTML/CSS, not JSON
|
|
|
|
## Input endpoints
|
|
|
|
### `POST /api/upload`
|
|
|
|
Uploads one file in multipart field `archive`.
|
|
|
|
Accepted inputs:
|
|
- supported archive/log formats from the parser registry
|
|
- `.json` `AnalysisResult` snapshots
|
|
- raw-export JSON packages
|
|
- raw-export ZIP bundles
|
|
|
|
Result:
|
|
- parses or replays the input
|
|
- stores the result as current in-memory state
|
|
- returns parsed summary JSON
|
|
|
|
Related helper:
|
|
- `GET /api/file-types` returns `archive_extensions`, `upload_extensions`, and `convert_extensions`
|
|
|
|
### `POST /api/collect`
|
|
|
|
Starts a live collection job.
|
|
|
|
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` or `ipmi`
|
|
- `auth_type`: `password` or `token`
|
|
- `tls_mode`: `strict` or `insecure`
|
|
|
|
Responses:
|
|
- `202` on accepted job creation
|
|
- `400` on malformed JSON
|
|
- `422` on validation errors
|
|
|
|
Optional request field:
|
|
- `power_on_if_host_off`: when `true`, Redfish collection may power on the host before collection if preflight found it powered off
|
|
|
|
### `POST /api/collect/probe`
|
|
|
|
Checks that live API connectivity works and returns host power state before collection starts.
|
|
|
|
Typical request body is the same as `POST /api/collect`.
|
|
|
|
Typical response fields:
|
|
- `reachable`
|
|
- `protocol`
|
|
- `host_power_state`
|
|
- `host_powered_on`
|
|
- `power_control_available`
|
|
- `message`
|
|
|
|
### `GET /api/collect/{id}`
|
|
|
|
Returns async collection job status, progress, timestamps, and accumulated logs.
|
|
|
|
### `POST /api/collect/{id}/cancel`
|
|
|
|
Requests cancellation for a running collection job.
|
|
|
|
### `POST /api/convert`
|
|
|
|
Starts a batch conversion job that accepts multiple files under `files[]` or `files`.
|
|
Each supported file is parsed independently and converted to Reanimator JSON.
|
|
|
|
Response fields:
|
|
- `job_id`
|
|
- `status`
|
|
- `accepted`
|
|
- `skipped`
|
|
- `total_files`
|
|
|
|
### `GET /api/convert/{id}`
|
|
|
|
Returns batch convert job status using the same async job envelope as collection.
|
|
|
|
### `GET /api/convert/{id}/download`
|
|
|
|
Downloads the ZIP artifact produced by a successful convert job.
|
|
|
|
## Read endpoints
|
|
|
|
### `GET /api/status`
|
|
|
|
Returns source metadata for the current dataset.
|
|
If nothing is loaded, response is `{ "loaded": false }`.
|
|
|
|
Typical fields:
|
|
- `loaded`
|
|
- `filename`
|
|
- `vendor`
|
|
- `source_type`
|
|
- `protocol`
|
|
- `target_host`
|
|
- `source_timezone`
|
|
- `collected_at`
|
|
- `stats`
|
|
|
|
### `GET /api/config`
|
|
|
|
Returns the main UI configuration payload, including:
|
|
- source metadata
|
|
- `hardware.board`
|
|
- `hardware.firmware`
|
|
- canonical `hardware.devices`
|
|
- computed specification lines
|
|
|
|
### `GET /api/events`
|
|
|
|
Returns events sorted newest first.
|
|
|
|
### `GET /api/sensors`
|
|
|
|
Returns parsed sensors plus synthesized PSU voltage sensors when telemetry is available.
|
|
|
|
### `GET /api/serials`
|
|
|
|
Returns serial-oriented inventory built from canonical devices.
|
|
|
|
### `GET /api/firmware`
|
|
|
|
Returns firmware-oriented inventory built from canonical devices.
|
|
|
|
### `GET /api/parse-errors`
|
|
|
|
Returns normalized parse and collection issues combined from:
|
|
- Redfish fetch errors in `raw_payloads`
|
|
- raw-export collect logs
|
|
- derived partial-inventory warnings
|
|
|
|
### `GET /api/parsers`
|
|
|
|
Returns registered parser metadata.
|
|
|
|
### `GET /api/file-types`
|
|
|
|
Returns supported file extensions for upload and batch convert.
|
|
|
|
## Viewer endpoints
|
|
|
|
### `GET /chart/current`
|
|
|
|
Renders the current in-memory dataset as Reanimator HTML using embedded `reanimator/chart`.
|
|
The server first converts the current result to Reanimator JSON, then passes that snapshot to the viewer.
|
|
|
|
### `GET /chart/static/...`
|
|
|
|
Serves embedded `reanimator/chart` static assets.
|
|
|
|
## Export endpoints
|
|
|
|
### `GET /api/export/csv`
|
|
|
|
Downloads serial-number CSV.
|
|
|
|
### `GET /api/export/json`
|
|
|
|
Downloads a raw-export artifact for reopen and re-analysis.
|
|
Current implementation emits a ZIP bundle containing:
|
|
- `raw_export.json`
|
|
- `collect.log`
|
|
- `parser_fields.json`
|
|
|
|
### `GET /api/export/reanimator`
|
|
|
|
Downloads Reanimator JSON built from the current normalized result.
|
|
|
|
## Management endpoints
|
|
|
|
### `DELETE /api/clear`
|
|
|
|
Clears current in-memory dataset, raw export state, and temporary convert artifacts.
|
|
|
|
### `POST /api/shutdown`
|
|
|
|
Gracefully shuts down the process after responding.
|