REST API

Starting with version 1.4, your evon Smart Home offers you a REST API Service at "http://[evon Smart Home_IP]/api". The following steps are required to use it.

Preparation

  • Navigate to 'Alle Apps' - 'Settings' - 'Rest Service' in the user interface of your evon Smart Home system.
  • Enter your evon Smart Home credentials and generate a hash (You should save the hash value as it is needed for the following step).

Authentication

To send requests to the REST API, you must authenticate yourself. A token is used for this purpose, which you will receive once you make a successful login attempt via the REST API.

  • Send a POST request to the following address: "http://[evon Smart Home_IP]/login", with this header parameters:
    • x-elocs-username: [Username]
    • x-elocs-password: [Hash]

You will receive a token 'x-elocs-token' as a response, which will automatically be set as a cookie. This token will now be used as an authentification for all further requests.

Depending on from where you are sending your requests, the cookie will automatically be used. Otherwise, you will have to add the token to the header of every request 'Cookie:token=[Token]'.

Requests

The evon Smart Home REST API allows you check the status of the components in your system and to control them. The following requests are available to you:

GET: apps
"http://[evon Smart Home_IP]/api/apps"
Returns a list of all apps.

GET: apps/{fullName}
Returns detailed information about the requested app.

GET: instances
Returns a list of all instances.

GET: instances/{instanceId}
Returns detailed informations about the requested instance.

GET: instances/{instanceId}/{action}
Returns the current value of the requested property of a specific instance. For example, the current state of a light.

POST: instances/{instanceId}/{action}
Calls a method of the specific instance.

You can find a test interface at "http://[evon Smart Home_IP]/api", which allows you to try out all listed requests.

Examples

In the following example, we want to switch a light by using the REST API.

Before we can start, we have to make sure that the preparations for authentification are done (see topic "Preparation" and "Authentification"). With the received token, we are now able to send all requests and commands.

At first we send a GET request to `"http://[evon Smart Home_IP]/api/instances" and receive a list with all instances, which are currently active in the evon Smart Home system.


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

As we want to switch a light, we choose the 'Roomlight' and use its "ClassName": "SmartCOM.Light.Light" to send a GET request to `"http://[evon Smart Home_IP]/api/apps/SmartCOM.Light.Light"` and receive the available methods and properties.

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

We are now sending a POST request to `"http://[evon Smart Home_IP]/api/instances/SC1_M04.Light1/SwitchOn"` with the following parameters in the header:
- instanceId: SC1_M04.Light1
- action: SwitchOn
- body: [ ]

This will call the specified method of the light and switch it on. We can also check the current status by sending a GET request to `"http://[evon Smart Home_IP]/api/instances/SC1_M04.Light1/IsOn"` and receive a response containing the current status, in this case 'true'.

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