core/bible/architecture/api-surface.md

API Surface

Health

• GET /health

Registry

• GET /assets
• POST /assets
• GET /registry/assets/{id}
• PUT /registry/assets/{id}
• DELETE /registry/assets/{id}
• GET /components
• POST /components
• GET /registry/components/{id}
• PUT /registry/components/{id}

Registry invariants:

• Assets do not carry project_id in request/response contracts.

Ingest

• POST /ingest/hardware
• POST /ingest/manual/csv
• GET /ingest/manual/csv/jobs/{id}

Manual CSV ingest contract:

• POST /ingest/manual/csv is asynchronous and returns 202 Accepted with job_id.
• Final result is read from GET /ingest/manual/csv/jobs/{id}.

Timeline

• GET /assets/{id}/timeline
• GET /components/{id}/timeline

Failures

• GET /failures
• POST /failures

UI Routes

• GET /ui
• GET /ui/assets
• GET /ui/assets/{id}
• GET /ui/components
• GET /ui/components/{id}
• GET /ui/failures
• GET /ui/ingest
• GET /ui/ingest/manual-template.csv

CSV Export Contract

Route: GET /ui/ingest/manual-template.csv

Rules:

• Encoding: UTF-8.
• UTF-8 BOM is included at file start for Excel compatibility.
• Delimiter: ;.
• Line endings: \r\n.
• Escaping: RFC4180-compatible (fields with ;, ", \n, \r are quoted; inner " is doubled).
• Header row is always present.
• Stable column order (deterministic, no map-driven order).
• Exported header order:
  • дата_осмотра
  • серийный_номер_сервера
  • вендор
  • p/n_устройства
  • s/n_устройства
  • локейшн_в_сервере
  • версия_прошивки
  • состояние_оборудования
• Identifier-like columns are exported with Excel-safe text protection (to preserve leading zeros/codes).
• Empty values are exported as empty cells (no null/undefined).
• HTTP headers:
  • Content-Type: text/csv; charset=utf-8
  • Content-Disposition: attachment; filename="manual-import-template.csv"

Routing Notes

• API router is registered in internal/api/server.go.
• Registry, ingest, failures, asset/component pages, and UI routes are attached to http.ServeMux.