docs: refresh project documentation
This commit is contained in:
Mikhail Chusavitin
@@ -2,38 +2,37 @@
|
||||
|
||||
## 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>`
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
## Upload & Data Input
|
||||
## Input endpoints
|
||||
|
||||
### `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**.
|
||||
Uploads one file in multipart field `archive`.
|
||||
|
||||
Accepted inputs:
|
||||
- `.tar`, `.tar.gz`, `.tgz` — vendor diagnostic archives
|
||||
- `.txt` — plain text files
|
||||
- JSON file containing a serialized `AnalysisResult` — re-loaded as-is
|
||||
- supported archive/log formats from the parser registry
|
||||
- `.json` `AnalysisResult` snapshots
|
||||
- raw-export JSON packages
|
||||
- raw-export ZIP bundles
|
||||
|
||||
**Response:** `200 OK` with parsed result summary, or `4xx`/`5xx` on error.
|
||||
Result:
|
||||
- parses or replays the input
|
||||
- stores the result as current in-memory state
|
||||
- returns parsed summary JSON
|
||||
|
||||
---
|
||||
|
||||
## Live Collection
|
||||
Related helper:
|
||||
- `GET /api/file-types` returns `archive_extensions`, `upload_extensions`, and `convert_extensions`
|
||||
|
||||
### `POST /api/collect`
|
||||
|
||||
Start a live collection job (`redfish` or `ipmi`).
|
||||
Starts a live collection job.
|
||||
|
||||
Request body:
|
||||
|
||||
**Request body:**
|
||||
```json
|
||||
{
|
||||
"host": "bmc01.example.local",
|
||||
@@ -47,138 +46,125 @@ Start a live collection job (`redfish` or `ipmi`).
|
||||
```
|
||||
|
||||
Supported values:
|
||||
- `protocol`: `redfish` | `ipmi`
|
||||
- `auth_type`: `password` | `token`
|
||||
- `tls_mode`: `strict` | `insecure`
|
||||
- `protocol`: `redfish` or `ipmi`
|
||||
- `auth_type`: `password` or `token`
|
||||
- `tls_mode`: `strict` or `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)
|
||||
Responses:
|
||||
- `202` on accepted job creation
|
||||
- `400` on malformed JSON
|
||||
- `422` on validation errors
|
||||
|
||||
### `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`
|
||||
Returns async collection job status, progress, timestamps, and accumulated logs.
|
||||
|
||||
### `POST /api/collect/{id}/cancel`
|
||||
|
||||
Cancel a running job.
|
||||
Requests cancellation for a running collection job.
|
||||
|
||||
---
|
||||
### `POST /api/convert`
|
||||
|
||||
## Data Queries
|
||||
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 }`.
|
||||
|
||||
```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 }`.
|
||||
Typical fields:
|
||||
- `loaded`
|
||||
- `filename`
|
||||
- `vendor`
|
||||
- `source_type`
|
||||
- `protocol`
|
||||
- `target_host`
|
||||
- `source_timezone`
|
||||
- `collected_at`
|
||||
- `stats`
|
||||
|
||||
### `GET /api/config`
|
||||
|
||||
Returns source metadata plus:
|
||||
Returns the main UI configuration payload, including:
|
||||
- source metadata
|
||||
- `hardware.board`
|
||||
- `hardware.firmware`
|
||||
- canonical `hardware.devices`
|
||||
- computed `specification` summary lines
|
||||
- computed specification lines
|
||||
|
||||
### `GET /api/events`
|
||||
|
||||
Returns parsed diagnostic events.
|
||||
Returns events sorted newest first.
|
||||
|
||||
### `GET /api/sensors`
|
||||
|
||||
Returns sensor readings (temperatures, voltages, fan speeds).
|
||||
Returns parsed sensors plus synthesized PSU voltage sensors when telemetry is available.
|
||||
|
||||
### `GET /api/serials`
|
||||
|
||||
Returns serial numbers built from canonical `hardware.devices`.
|
||||
Returns serial-oriented inventory built from canonical devices.
|
||||
|
||||
### `GET /api/firmware`
|
||||
|
||||
Returns firmware versions built from canonical `hardware.devices`.
|
||||
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 list of registered vendor parsers with their identifiers.
|
||||
Returns registered parser metadata.
|
||||
|
||||
---
|
||||
### `GET /api/file-types`
|
||||
|
||||
## Export
|
||||
Returns supported file extensions for upload and batch convert.
|
||||
|
||||
## Export endpoints
|
||||
|
||||
### `GET /api/export/csv`
|
||||
|
||||
Download serial numbers as CSV.
|
||||
Downloads serial-number CSV.
|
||||
|
||||
### `GET /api/export/json`
|
||||
|
||||
Download full `AnalysisResult` as JSON (includes `raw_payloads`).
|
||||
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`
|
||||
|
||||
Download hardware data in Reanimator format for asset tracking integration.
|
||||
See [`07-exporters.md`](07-exporters.md) for full format spec.
|
||||
Downloads Reanimator JSON built from the current normalized result.
|
||||
|
||||
---
|
||||
|
||||
## Management
|
||||
## Management endpoints
|
||||
|
||||
### `DELETE /api/clear`
|
||||
|
||||
Clear current in-memory dataset.
|
||||
Clears current in-memory dataset, raw export state, and temporary convert artifacts.
|
||||
|
||||
### `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 |
|
||||
Gracefully shuts down the process after responding.
|
||||
|
||||
Reference in New Issue
Block a user