REST API

Base URL: https://hub.finishing2026.sw2e-lab.de/api/v1
Auth: x-api-key: <key> Header — außer /health und /docs
Interaktive Docs: /api/v1/docs

Geräte

`GET /devices`

Alle registrierten Geräte.

{
  "success": true,
  "data": [
    { "uuid": "...", "device_id": "motor-poc-01", "connection_status": "online", "created_at": "..." }
  ]
}

`GET /devices/:uuid`

Einzelnes Gerät inkl. vollständigem Thing Model.

`POST /devices/batch`

Mehrere Geräte auf einmal.

{ "uuids": ["uuid-1", "uuid-2"] }

Commands

`POST /devices/:uuid/command`

Sendet einen Command per MQTT an den ESP. Schlägt mit 503 fehl wenn das Gerät offline ist.

{ "capability": "power", "value": "ON" }

value je nach Capability-Typ: "ON" / "OFF" für ON_OFF, Zahl für NUMBER, beliebig für IMPULSE.

Optional: "command_id": "<uuid>" für Idempotenz — wird generiert falls nicht angegeben.

Response:

{ "success": true, "command_id": "550e8400-..." }

Telemetrie

`GET /devices/:uuid/telemetry`

Verlauf. Query-Parameter:

Parameter	Default	Beschreibung
`timespan`	`24 hours`	PostgreSQL Interval-Syntax
`start_date`	—	ISO 8601
`end_date`	jetzt	ISO 8601
`limit`	`100`	Max. Anzahl Einträge

`GET /devices/:uuid/telemetry/latest`

Letzter bekannter Wert pro Capability. Merged die letzten 20 Pakete — nützlich falls Capabilities in separaten Paketen kommen.

{ "data": { "power": "ON", "speed": 200, "solar_v": 2.1 }, "timestamp": "..." }

Identifiers

Die API verwendet durchgängig uuid als Gerät-Identifier. device_id ist der menschenlesbare Name aus dem Thing Model. mac bleibt intern (MQTT-Routing).