fcd57c1ba9
- Create docs/bible/ with 10 structured chapters (overview, architecture, API, data models, collectors, parsers, exporters, build, testing, decisions) - All documentation in English per ADL-007 - Record all existing architectural decisions in docs/bible/10-decisions.md - Slim README.md to user-facing quick start only - Replace CLAUDE.md with a single directive to read and follow the Bible - Remove absorbed files: REANIMATOR_EXPORT.md, docs/INTEGRATION_GUIDE.md, and all vendor parser README.md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
155 lines
3.0 KiB
Markdown
155 lines
3.0 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`.
|
|
|
|
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 Redfish collection job.
|
|
|
|
**Request body:**
|
|
```json
|
|
{
|
|
"host": "bmc01.example.local",
|
|
"protocol": "redfish",
|
|
"port": 443,
|
|
"username": "admin",
|
|
"auth_type": "password",
|
|
"password": "secret",
|
|
"tls_mode": "insecure"
|
|
}
|
|
```
|
|
|
|
`tls_mode` values: `insecure` | `verify`
|
|
|
|
**Response:** `202 Accepted` with `{ "id": "<job-id>" }`
|
|
|
|
### `GET /api/collect/{id}`
|
|
|
|
Poll job status and progress log.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "...",
|
|
"status": "running",
|
|
"logs": ["Connecting to BMC...", "Collecting CPUs..."]
|
|
}
|
|
```
|
|
|
|
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
|
|
{
|
|
"source_type": "api",
|
|
"protocol": "redfish",
|
|
"target_host": "bmc01.example.local",
|
|
"collected_at": "2026-02-10T15:30:00Z"
|
|
}
|
|
```
|
|
|
|
`source_type`: `archive` | `api`
|
|
|
|
### `GET /api/config`
|
|
|
|
Returns the full canonical hardware inventory (`hardware.devices`) plus board info.
|
|
|
|
### `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.
|
|
|
|
---
|
|
|
|
## 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 |
|