REST API

Ab evonHOME Version 1.4 steht Dir eine REST API unter "http://[evonHOME_IP]/api" zur Verfügung. Um diese verwenden zu können, sind folgende Schritte notwendig.

Vorbereitung

  • Navigiere in der Benutzeroberfläche Deines evonHOME Systems zu 'Alle Apps' - 'Einstellungen' - 'Rest Service';
  • Gib hier deine evonHOME Zugangsdaten ein und erzeuge daraus einen Hash (Diesen solltest Du dir notieren bzw speichern, da Du ihn für den nächsten Schritt benötigst)

Authentifizierung

Um Anfragen an die REST API stellen zu können, musst Du dich authentifizieren. Hierzu wird ein eigener Token verwendet, denn du nach einem erfolgreichen Login mittels der REST API erhälst.

  • Sende einen POST Request an die Adresse: "http://[evonHOME_IP]/login", mit folgenden Parametern im Header:
    • x-elocs-username: [Benutzername]
    • x-elocs-password: [Hash]

Als Antwort erhälst du einen Token 'x-elocs-token' der auch automatisch als Cookie gesetzt wird. Dieser wird nun für die Authentifizierung aller weiteren Anfragen verwendet.

Je nachdem von wo aus Du Anfragen an Dein evonHOME System sendest, wird der gesetzte Cookie automatisch verwendet. Andernfalls musst Du den Token bei jeder Anfrage im Header mitsenden 'Cookie:token=[Token]'.

Anfragen

Die evonHOME REST API bietet dir sowohl die Möglichkeit, den aktuellen Status der einzelnen Funktionen in deinem System abzufragen, als auch diese zu steuern. Dazu stehen dir folgende Anfragen zu Verfügung:

GET: apps
"http://[evonHOME_IP]/api/apps"
Liefert eine Liste aller Apps.

GET: apps/{fullName}
Liefert detaillierte Informationen über die angefragte App.

GET: instances
Liefert eine Liste aller Instanzen.

GET: instances/{instanceId}
Liefert detaillierte Informationen über die angefragte Instanz.

GET: instances/{instanceId}/{action}
Liefert den aktuellen Wert der angefragten Eigenschaft einer spezifischen Instanz. Zu Beispiel den aktuellen Status eines Lichts.

POST: instances/{instanceId}/{action}
Ruft eine Methode der spezifischen Instanz auf.

Unter "http://[evonHOME_IP]/api" findest Du eine Testseite zu REST API, die es Dir ermöglicht alle gelisteten Anfragen auszuprobieren.

Beispiele

In folgendem Beispiel möchten wir ein Licht über die REST API schalten.

Bevor wir beginnen können, müssen zuerst betreffende Vorbereitungen zur Authentifizierung getroffen werden (siehe Punkte "Vorbereitung" sowie "Authentifizierung"). Mit dem dadurch erhaltenen Token können nun alle Anfragen und Befehle gesendet werden.

Zuerst senden wir eine GET Anfrage an "http://[evonHOME_IP]/api/instances" und erhalten eine Liste mit allen Instanzen, die aktuell auf dem evonHOME System aktiv sind.

{ "statusCode": 200, "statusText": "success", "data": [ { "ID": "SC1_M04.Light1", "ClassName": "SmartCOM.Light.Light", "Name": "Arbeitslicht", Group": "AreaOutdoor }, ... ] }

Da wir ein Licht schalten wollen, wählen wir hier das 'Arbeitslicht' und verwenden den "ClassName": "SmartCOM.Light.Light" um eine GET Anfrage an "http://[evonHOME_IP]/api/apps/SmartCOM.Light.Light" zu senden und die verfügbaren Methoden und Eigenschaften zu erhalten.

{ "statusCode": 200, "statusText": "success", "data": { "methods": [ { "parameter": [], "name": "SwitchOn", "type": 0, "derived": false, "tags": [ linkable ], "returnType": "void", "description": "Einschalten", "isStatic": false }, ... ], "properties": [ { "name": "IsOn", "type": "boolean", "remark": "Licht eingeschaltet", "declaration": "2", "derived": true, "parameter": false, "tags": [ linkable ], "isStatic": false }, ... ], "fullName": "SmartCOM.Light.Light", "displayName": "Licht", "autoStart": false } }

Nun senden wir eine POST Anfrage an "http://[evonHOME_IP]/api/instances/SC1_M04.Light1/SwitchOn"
mit folgenden Parametern im Header:

  • instanceId: SC1_M04.Light1
  • action: SwitchOn
  • body: [ ]

Dadurch wir die betreffende Licht Methode aufgerufen und das Licht wird eingeschalten. Wir können den aktuellen Status auch überprüfen, indem wir eine GET Anfrage an "http://[evonHOME_IP]/api/instances/SC1_M04.Light1/IsOn" senden. Als Antwort erhalten wir den aktuellen Status, in diesem Fall 'true'.

{ "statusCode": 200, "statusText": "success", "data": true }