REST API

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

Vorbereitung

  • Navigieren Sie in der Benutzeroberfläche Ihres evon Smart Home Systems zu 'Alle Apps' - 'Einstellungen' - 'Rest Service';
  • Geben Sie hier Ihre evon Smart Home Zugangsdaten ein und erzeugen Sie daraus einen Hash (Diesen sollten Sie notieren bzw speichern, da Sie ihn für den nächsten Schritt benötigen)

Authentifizierung

Um Anfragen an die REST API stellen zu können, müssen Sie sich authentifizieren. Hierzu wird ein eigener Token verwendet, denn Sie nach einem erfolgreichen Login mittels der REST API erhalten.

  • Senden Sie einen POST Request an die Adresse: "http://[evon Smart Home_IP]/login", mit folgenden Parametern im Header:
    • x-elocs-username: [Benutzername]
    • x-elocs-password: [Hash]

Als Antwort erhalten Sie 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 Sie Anfragen an Ihr evon Smart Home System senden, wird der gesetzte Cookie automatisch verwendet. Andernfalls müssen Sie den Token bei jeder Anfrage im Header mitsenden 'Cookie:token=[Token]'.

Anfragen

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

GET: apps
"http://[evon Smart Home_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://[evon Smart Home_IP]/api" finden Sie eine Testseite zu REST API, die es Ihnen 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://[evon Smart Home_IP]/api/instances" und erhalten eine Liste mit allen Instanzen, die aktuell auf dem evon Smart Home 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://[evon Smart Home_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://[evon Smart Home_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://[evon Smart Home_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 }