HTTP-API

Die API des nomos system Controllers über HTTP aufrufen

Jeder Aufruf der Socket.io-API steht auch über HTTP zur Verfügung. Das eignet sich für Skripte und für Systeme, die einzelne Anfragen stellen und keine dauerhafte Verbindung halten.

Aufrufe

Der Name des Aufrufs ist der letzte Teil der Adresse:

POST http://<controller-ip>/api/v1/<function>

Die Parameter, die über Socket.io im ersten Argument stehen, senden Sie als JSON im Body:

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"cid":"C5","property":"state"}' \
  http://<controller-ip>/api/v1/getComponentData

Formulardaten (-d 'cid=C5&property=state') und GET mit Query-Parametern (/api/v1/getComponentData?cid=C5&property=state) funktionieren ebenfalls. Dabei werden die Texte true und false zu Wahrheitswerten. Andere Methoden als GET und POST beantwortet der Controller mit dem Status 405.

Welche Aufrufe es gibt und welche Parameter sie erwarten, steht auf apidocs.

Anmelden

Es gibt zwei Wege, und jede Anfrage braucht einen davon.

Benutzername und Kennwort in den Headern auth-username und auth-password:

curl -s -X POST -H "auth-username: USERNAME" -H "auth-password: PASSWORD" \
  http://<controller-ip>/api/v1/getVersion

{"api":"0.3.41","ncd":"1.15","engine":"1.2.2"}

Sitzungs-ID im Header x-nomos-sid. Die ID erhalten Sie einmalig mit POST /api/v1/auth:

curl -s -X POST -H "auth-username: USERNAME" -H "auth-password: PASSWORD" \
  -H "auth-persistent: true" http://<controller-ip>/api/v1/auth

{"sessionID":"<session-id>","userID":<user-id>}

curl -s -X POST -H "x-nomos-sid: <session-id>" http://<controller-ip>/api/v1/getVersion

Verwenden Sie für wiederholte Aufrufe die Sitzungs-ID. Mit Benutzername und Kennwort prüft der Controller bei jeder Anfrage das Kennwort neu und legt, solange Ihr Client keine Cookies speichert, jedes Mal eine neue Sitzung an. Ohne auth-persistent: true gilt eine Sitzung 24 Stunden ab der letzten Nutzung, mit zwei Jahre. Mehr dazu unter Sitzungen.

Der Header accept-language (etwa de oder en) bestimmt die Sprache von errorText.

logout beendet die Sitzung:

curl -s -X POST -H "x-nomos-sid: <session-id>" http://<controller-ip>/api/v1/logout

Antworten und Fehler

Bei Erfolg antwortet der Controller mit dem Status 200 und im Body mit dem, was der Aufruf über Socket.io zurückgibt, etwa true, ein Objekt oder eine Liste.

Bei einem Fehler enthält der Body errorCode und errorText, und der Status zeigt die Art des Fehlers:

Status	Bedeutung	Beispiel
400	Der Aufruf ist mit einem Fehler beantwortet worden.	{"errorCode":106,"errorText":"Parameter(s) error"}, wenn ein Pflichtparameter fehlt; 112 für etwas, das es nicht gibt; 117, wenn der Benutzer den Aufruf nicht verwenden darf
401	Die Anmeldung ist gescheitert.	110 bei falschem Kennwort, 106 bei abgelaufener oder unbekannter Sitzung, 109 während einer Sperre nach Fehlversuchen
405	Methode nicht erlaubt	{"errorCode":117,"errorText":"Method Not Allowed"} bei PUT oder DELETE
408	Innerhalb von 15 Sekunden kam keine Antwort.	{"errorCode":116,"errorText":"Timeout occurred"}, auch bei einem Aufruf, den es nicht gibt

Entscheiden Sie im Code anhand von errorCode, nicht anhand von errorText. Die Bedeutung aller Fehlercodes steht auf apidocs.

Grenzen

• Keine Events: Über HTTP meldet der Controller Änderungen nicht von sich aus. Wer Werte laufend verfolgen will, nutzt Socket.io mit dem Event onComponentUpdate oder MQTT.
• 15 Sekunden je Aufruf: Antwortet ein Aufruf nicht innerhalb von 15 Sekunden, kommt Status 408. Der Aufruf kann trotzdem ausgeführt worden sein, etwa eine lange Szene.

HTTPS

Auf Port 443 nutzt der Controller ein selbstsigniertes Zertifikat ohne Hostnamen. Wie Ihr Programm genau diesem Zertifikat vertraut und warum curl dafür nicht ausreicht, steht unter HTTPS und Zertifikat.