REST unter /api/v1. Alle Antworten sind JSON mit der Nutzlast unter data. Keine Authentifizierung, CORS offen.
Schloss und Türblatt sind zwei unabhängige Größen — genau wie bei echter Hardware. Aus der Kombination ergeben sich vier Zustände:
| lock | door | Bedeutung |
|---|---|---|
locked | closed | Ruhezustand. Öffnen wird abgewiesen. |
unlocked | closed | Freigegeben. Autolock läuft, die Tür kann geöffnet werden. |
unlocked | open | Tür steht offen, Schloss noch freigegeben. |
locked | open | Autolock hat ausgelöst, während die Tür offen stand. Feld ajar ist true; der Zustand endet, sobald die Tür zufällt. |
Zutritt gewähren, Panel beschriften, Autolock beobachten:
# 1. Panel beschriften
curl -X PUT http://localhost:3000/api/v1/displays/MCI1-001 \
-H 'Content-Type: application/json' \
-d '{"title":"Raum MCI1-001","status":"belegt","subtitle":"Belegt bis 15:15"}'
# 2. Entriegeln
curl -X POST http://localhost:3000/api/v1/doors/MCI1-001/unlock
# 3. Status prüfen — autoLockInSeconds zählt herunter
curl http://localhost:3000/api/v1/doors/MCI1-001/status
# 4. Tür öffnen und wieder schließen
curl -X POST http://localhost:3000/api/v1/doors/MCI1-001/open
curl -X POST http://localhost:3000/api/v1/doors/MCI1-001/close
# 5. Nach 5 Sekunden ist lock wieder "locked"{
"error": {
"code": "door_locked",
"message": "Tür 'MCI1-001' ist verriegelt.",
"details": null
}
}| Code | HTTP | Auslöser |
|---|---|---|
door_not_found | 404 | Unbekannte Tür-ID |
door_locked | 409 | Öffnen bei verriegeltem Schloss |
door_in_lockdown | 409 | Entriegeln bei gesperrter Tür |
controller_offline | 503 | Schaltbefehl an ausgefallenen Controller |
validation_failed | 400 | Fehlerhafter Parameter oder Körper |
Die beiden Endpunkte, die ein Buchungssystem im Normalbetrieb braucht: entriegeln und Status abfragen.
/api/v1/doors/{id}/unlockEntriegelt das Schloss. Im Normalbetrieb ein Impuls — nach 5 Sekunden verriegelt der Controller selbsttätig. Bei gesperrter Tür antwortet der Endpunkt mit 409 door_in_lockdown, bei ausgefallenem Controller mit 503.
curl -X POST http://localhost:3000/api/v1/doors/MCI1-001/unlock/api/v1/doors/{id}/statusMinimale Statusabfrage. Liefert Schlosszustand, Türzustand, Betriebsart und die verbleibenden Sekunden bis zum Autolock.
curl http://localhost:3000/api/v1/doors/MCI1-001/status/api/v1/doors/{id}/lockVerriegelt sofort und bricht ein laufendes Autolock ab.
/api/v1/doors/{id}/modeBetriebsart setzen. auto = Normalbetrieb mit Autolock, permanent_unlock = Dauerentriegelung ohne Autolock, lockdown = dauerhaft verriegelt, Entriegeln wird abgewiesen.
{ "mode": "permanent_unlock" }Das Türblatt ist vom Schloss unabhängig. Diese Endpunkte simulieren eine Person, die die Tür aufzieht oder zufallen lässt.
/api/v1/doors/{id}/openÖffnet das Türblatt. Setzt ein entriegeltes Schloss voraus — sonst 409 door_locked, und der Controller protokolliert door.access_denied.
curl -X POST http://localhost:3000/api/v1/doors/MCI1-001/open/api/v1/doors/{id}/closeSchließt das Türblatt. War das Schloss bereits verriegelt, fällt die Tür ein und der Zustand ajar endet.
Jede Tür hat ein Panel unter /kiosk/{id}. Der Inhalt ist beliebiges JSON und erscheint sofort.
/api/v1/displays/{id}Setzt den Panelinhalt. Die Felder title, subtitle, status, accent, message, lines und footer werden gestaltet dargestellt; alle weiteren Felder erscheinen als Schlüssel-Wert-Liste. status steuert die Akzentfarbe: frei grün, reserviert gelb, belegt rot, wartung grau.
{
"title": "Seminarraum 1.01",
"subtitle": "Belegt bis 15:15",
"status": "belegt",
"lines": [
{ "label": "Aktuell", "value": "Corporate Finance (SE)" },
{ "label": "Danach", "value": "15:30 Marketing Management (IL)" }
],
"footer": "Buchung über raumbuchung.mci.local"
}curl -X PUT http://localhost:3000/api/v1/displays/MCI1-001 \
-H 'Content-Type: application/json' \
-d '{"title":"Raum MCI1-001","status":"frei","subtitle":"Frei bis 14:00"}'/api/v1/displays/{id}Liest den aktuellen Panelinhalt samt Version und Zeitpunkt.
/api/v1/displays/{id}Setzt das Panel auf den Standardinhalt zurück.
/api/v1/displaysAlle Panels auf einmal.
/api/v1/doorsAlle Türen mit vollem Status und einer Zusammenfassung.
| Parameter | Bedeutung |
|---|---|
buildingId | z. B. MCI1 |
lock | locked | unlocked |
limit / offset | Paginierung, max. 200 |
curl 'http://localhost:3000/api/v1/doors?lock=unlocked'/api/v1/buildingsGebäude, Ebenen und Türzuordnung.
/api/v1/eventsEreignisprotokoll. Mit ?since=<seq> lassen sich gezielt nur neue Ereignisse abholen.
| Parameter | Bedeutung |
|---|---|
doorId | auf eine Tür einschränken |
since | nur Ereignisse mit höherer Sequenznummer |
limit | 1–500, Standard 50 |
/api/v1/streamServer-Sent Events. Beim Verbinden kommt eine vollständige Momentaufnahme, danach jedes Ereignis, sobald es eintritt.
const es = new EventSource("http://localhost:3000/api/v1/stream");
es.addEventListener("door.auto_locked", (e) => console.log(JSON.parse(e.data)));/api/v1/doors/{id}/controllerSimuliert Ausfall oder Rückkehr eines Türcontrollers. Ein ausgefallener Controller weist jeden Schaltbefehl mit 503 ab — damit lässt sich prüfen, wie euer System auf Hardwareausfälle reagiert.
{ "online": false }/api/v1/system/lockdownSperrt oder gibt alle Türen frei, wahlweise nur ein Gebäude.
{ "active": true, "buildingId": "MCI1" }/api/v1/system/resetStellt die Startbelegung wieder her (laufender Lehrbetrieb). Mit ?empty=true der Grundzustand: alle Türen verriegelt und geschlossen, Panels und Protokoll leer.