Roasthubs v2 API
Die v2 API ist die typisierte, OpenAPI-dokumentierte HTTP-Schnittstelle, gebaut mit express-zod-api. Bevorzugen Sie sie für neue Integrationen. Legacy-Routen unter /api/... (ohne v2) existieren weiterhin, sind aber nicht von diesem Swagger abgedeckt.
Wo Sie die Docs finden (Swagger)
Auf einer laufenden Roasthubs-Instanz:
| Was | URL |
|---|---|
| Swagger UI | {baseUrl}/api/v2/docs |
| OpenAPI YAML | {baseUrl}/api/v2/docs.yaml |
Beispiele:
- Lokal:
http://localhost:\{PORT\}/api/v2/docs - YAML:
http://localhost:\{PORT\}/api/v2/docs.yaml
Diese Doc-Routen sind öffentlich (kein Login erforderlich). Der Aufruf der eigentlichen v2-Endpunkte erfordert normalerweise eine authentifizierte Sitzung.
Die OpenAPI-Spezifikation wird beim Start aus demselben Routing-Baum wie die Live-API erzeugt (src/controllers/v2/v2Router.ts → src/openapi.ts).
Basispfad
Alle v2-Endpunkte liegen unter:
/api/v2/...
Endpunktgruppen (Überblick)
| Gruppe | Basispfad | Zweck |
|---|---|---|
| Health | /api/v2/health | Health-Check |
| Productions | /api/v2/production | Produktionen auflisten / anlegen / abrufen / aktualisieren / löschen |
| Lots | /api/v2/lots/... | Chargen / Behälter entladen (inkl. über Realisierung) |
| Containers | /api/v2/container/:id/emptyToCell | Einen Behälter in eine Zelle entleeren |
| Plant nodes | /api/v2/plantNodes/:id | Einen Anlagenknoten aktualisieren |
| Zones | /api/v2/roasthubsZones | Zonen CRUD-ähnlich + Charge/Behälter entladen / Entladen stoppen |
| Inventory | /api/v2/inventory/inventorizeWeightedCell | Eine gewogene Zelle inventarisieren |
| Dosing | /api/v2/dosing/... | Dosierauftrag überspringen / stoppen, Flow-Alarm-Wahl leere Zelle |
| Shrinkage scale | /api/v2/shrinkageScale/discardBatch | Einen Batch der Schwundwaage verwerfen |
| Scale calibration | /api/v2/scaleCalibration/... | Aktivieren / Gewichte / Deaktivieren / Status |
| Connections | /api/v2/connections | Externe Verbindungen + Client-Zertifikate |
| Production options | /api/v2/productionRealisationOptions, /api/v2/productionTargetOptions | Realisierungs- & Zieloptionen abrufen/aktualisieren |
| OPC-UA | /api/v2/opcua/read, /api/v2/opcua/write | OPC-UA-Tags lesen / schreiben |
Für Request-/Response-Schemas und exakte Methoden nutzen Sie die Swagger UI — sie ist die Quelle der Wahrheit.
Auth
- Docs (
/api/v2/docs,/api/v2/docs.yaml): ungeschützt - Endpunkte: erfordern einen authentifizierten Benutzer (Sitzung), sofern eine Route nicht anders markiert ist
Client-SDK (Frontend)
Ein TypeScript-Client wird aus demselben Routing erzeugt nach:
client/src/express-zod-api-client/v2Client.ts
Nutzen Sie diesen (oder das OpenAPI-YAML) bei der Integration aus Code.