Functional description http-Rest Interface

You can use this interface to query certain values from the LOGIKEDITOR or send values to the LOGIKEDITOR from an external application via HTTP.

To do this, you create HTTP data points in the data point management, configure the respective data type and the permitted operations and optionally assign "speaking paths". In your logic groups, you then add value inputs or value outputs for the corresponding HTTP data point. Depending on how you design the signal path in the logic group, you can send values to the KNX bus via HTTP request to the LOGIKEDITOR or perform any actions in the LOGIKEDITOR, e.g. switch the enable input of a logic element or read out the status of a value memory.

To query external HTTP interfaces from the LOGIKEDITOR, i.e. the reverse use case, use the HTTP query logic element.

Contents

Supported Protocols

• https (port 444)

• http (Port 81)

https is authorized by a certificate signed by BAB TECHNOLOGIE GmbH itself. If necessary, the support of self-signed certificates must first be activated in the external application or is not supported. In case of problems, please inform yourself individually for your application. Even with a self-signed certificate, https is significantly more secure than http because encryption is guaranteed in any case.

http is not recommended, as authentication details are then transmitted unencrypted in any case. We only offer http if the external application does not support https or self-signed certificates, but integration is absolutely necessary.

Supported Methods

• GET
  to read values from the LOGIKEDITOR

• POST or PUT
  to set values in the LOGIKEDITOR, whereby the currently valid value is also transmitted as a body in the response.

In the configuration of a data point, you have the option of individually enabling the reading and setting of the value. Requests with methods for which the respective data point has not been enabled result in a response with status code 403 (see below).

If you want to restrict the permitted value range for setting values, simply use the filter tool downstream of the corresponding value input for this data point in your logic group, for example.

Supported authentication

Authentication is optional, but recommended, with static tokens. This means that if authentication is activated, the external application must also transmit a fixed, secret character string so that the request is permitted.

The token can be transmitted in two ways

• by means of an authorization header. Both the so-called bearer scheme and the pure token are supported as header values.

• as URL parameter token

Transmission as a URL parameter is not recommended because, unlike headers, a URL is transmitted unencrypted even when https is used. Attackers in the same network could therefore read the token in this case and then send requests themselves. We only offer this method if the external application does not offer adjustable headers, but integration is absolutely necessary.

You can configure a token as the default for all data points. However, you can also assign individual tokens to the data points. Our recommendation is to create an individual token for at least every external application. It can also be useful to differentiate between tokens for read and write access.

Example:
You have a webcam that should switch on the light via LOGIKEDITOR REST-API when there is movement and protect this data point with token 1, and you have a smart lawnmower that should switch a data point via REST-API if there is a problem with the device. You protect this data point with token 2. If someone gains unauthorized access to the lawn mowers web configuration, they will not be able to switch on the light with the token 2 stored there.

A high number of requests with a missing or incorrect token will lead to a temporary lockout with increasing lockout time (response with status code 429, see below).

Structure of the URL

The REST URL for a data point results from the combination of the base URL and the URL part of the data point.

Basis-URL

Depending on whether you are using https or http, you can access the REST interface via:

• https

  CODE

  https://<IP address EIBPORT>:444/le/rest/

• http

  CODE

  http://<IP address EIBPORT>:81/le/rest/

URL PORTION OF THE DATA POINT

Each data point has a random identification string, a so-called UUID. You can always use its UUID directly for the URL, or you can also assign an individual path.

In principle, any type of structure is conceivable here. For example, it would make sense to structure the paths based on the building topology and devices. However, you should bear in mind that such descriptive URLs could also reveal details about the implemented function or private information about the building and residents.

Examples:
https://192.168.1.21:444/le/rest/og/room-lena/deckenleuchter/schalter

https://192.168.1.21:444/le/rest/lamps/01

https://192.168.1.21:444/le/rest/41611b55-b54d-4b0a-a36d-aa9ba766a163

http://192.168.1.21:81/le/rest/41611b55-b54d-4b0a-a36d-aa9ba766a163?token= secret
(insecure, because http and token in the URL)

Data Format of the Interface

The data format can be selected from 3 formats, and can even be set per data point if required, e.g. if you want to allow several external applications accesses and one only supports JSON, while another only supports text:

• JSON
  Json object with a pair, or several pairs in the case of complex data points, of identifier and value. You configure the identifiers yourself in the data point.
  Example:

  CODE

  {
     "red": 128,
     "green": 128,
     "blue": 128
  }

• CSV
  A line of comma-separated values without an identifier (if it is a complex data point, otherwise only exactly one value).
  Example:

  CODE

  128;128;128

• Text
  One value of the data point per line (without identifier). No final line break.
  Example:
  128
128
128

The configured data format applies equally to the response body of read GET calls and the request body of write POST/PUT calls. In the case of a write call to a data point with a complex data type (as here in the example RGB), all values of the data point must always be sent, otherwise you will receive error code 422 in response (see below).

Which format you should choose depends on what the calling page supports and how clear your integration should be. Text and CSV are a little more performant than JSON, but JSON offers better comprehensibility, especially for data points with complex data types.

Answer

Possible status codes:

Header-Information

Possible status codes:

Body

The body of the response in the event of success corresponds exactly to the data format as described above, depending on which format you configure. In the event of an error, it is usually empty. Only in the case of a POST/PUT request that generates error 422 is the still valid value on the data point output in the body.

///