Functional description http-Rest Interface

External applications can use the REST interface to read values from the LOGIKEDITOR or transmit values to the LOGIKEDITOR.

For this purpose, REST data points are created in the data point management. For each data point, the data type, permitted access types, and optionally a custom path can be configured.

Within a logic group, these data points can be used like other data points via value inputs and value outputs.

Depending on the structure of the logic, external applications can, for example:

• transmit values to the LOGIKEDITOR via the REST API,

• trigger KNX telegrams,

• execute functions within a logic group,

• switch enable inputs of logic elements,

• read stored or calculated values.

For the reverse use case – where the LOGIKEDITOR accesses an external HTTP or HTTPS interface – use the HTTP Request logic element.

Contents

Supported Protocols

The REST interface supports the following protocols:

• HTTPS via port 444

• HTTP via port 81

For HTTPS, the device uses a certificate provided by BAB TECHNOLOGIE. Depending on the external application used, it may be necessary to accept this certificate or enable support for the corresponding certificate type.

HTTP should only be used if the external application does not support HTTPS connections and integration is otherwise not possible.

Supported Methods

The REST interface supports the following HTTP methods:

• GET
  Reads the current value of a data point.

• POST
  Sets the value of a data point.

• PUT
  Sets the value of a data point.

For POST and PUT requests, the value that is valid after successful processing is returned in the response body.

For each data point, you can configure separately whether read and/or write access is permitted.

If an operation is performed that has not been enabled for the respective data point, the REST interface responds with HTTP status code 403 (Forbidden).

If the permitted value range needs to be restricted further, the data point can be connected, for example, to a downstream Filter Tool within the logic group.

Supported Authentication

The REST interface supports optional token-based authentication.

Using authentication is recommended. If authentication is enabled, the external application must transmit a valid static token with each request.

The token can be transmitted in two ways:

• via the HTTP Authorization header

• via the URL parameter token

The following variants are supported for the Authorization header:

• Bearer scheme

• token directly as the header value

Transmission via the Authorization Header

The preferred method is transmission via the Authorization header.

Example:

Authorization: Bearer <TOKEN>

Transmission as a URL Parameter

Alternatively, the token can be transmitted as a URL parameter:

?token=<TOKEN>

The URL parameter is intended primarily for applications that do not support freely configurable HTTP headers.

Assigning Tokens

A default token can be configured for all REST data points. In addition, individual tokens can be assigned to specific data points.

It is recommended to use at least one separate token for each external application. Depending on the application, it may also be useful to use different tokens for read and write access.

Example

A webcam is intended to trigger a data point via the REST API when motion is detected in order to switch on the light. This data point is protected with Token 1.

A smart lawn mower is intended to trigger another REST data point when a device fault occurs. This data point is protected with Token 2.

If an unauthorized person gains access to the lawn mower configuration, the stored Token 2 cannot be used to access the webcam data point.

URL Structure

The URL of a REST data point consists of the base URL and the URL part of the respective data point.

Base URL

When using HTTPS:

https://<IP-ADDRESS>:444/le/rest/

When using HTTP:

http://<IP-ADDRESS>:81/le/rest/

<IP-ADDRESS> represents the IP address of the respective device.

URL Part of the Data Point

Each REST data point has a unique identification string (UUID).

The UUID can be used directly as the URL part. Alternatively, a custom path can be configured for the data point.

Example using a UUID:

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

Examples using a custom path:

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

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

Custom paths can, for example, be structured according to the building topology, rooms, or functions.

Example using a token as a URL parameter:

http://192.168.1.21:81/le/rest/41611b55-b54d-4b0a-a36d-aa9ba766a163?token=secret

Interface Data Format

The data format can be configured for the REST interface and, if required, individually for each data point.

The following formats are supported:

• JSON

• CSV

• Text

This allows different external applications to be connected even if they support different data formats.

JSON

With JSON, values are transmitted as a JSON object. For complex data points, the object contains several name/value pairs.

The names are defined when configuring the data point.

Example

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

CSV

With CSV, values are transmitted without names as separated values.

For simple data points, only one value is transmitted.

Example

128;128;128

Text

With the text format, each value is transmitted on a separate line without a name.

Example

128
128
128

The configured data format applies to both:

• the response body of a GET request

• the request body of a POST or PUT request

For a complex data type, all required component values must be transmitted with a write POST or PUT request.

If required values are missing or the transmitted data cannot be processed, the interface responds with status code 422 (Unprocessable Entity).

Response (HTTP Status Codes)

The REST interface uses standardized HTTP status codes to indicate the result of a request.

Status Code 422

Possible causes of 422 Unprocessable Entity include:

• incorrect names when using JSON

• incorrect capitalization of a name

• invalid number formats

• incorrect decimal separators

• missing component values for complex data types

Status Code 429

After multiple failed authentication attempts, further requests are temporarily rejected.

In this case, check in particular:

• whether a token is being transmitted,

• whether the token being used is correct,

• whether the token is assigned to the respective data point.

Correct the cause before sending additional requests.

Header Information (HTTP Headers)

The REST interface may return the following headers, among others:

Last-Modified

For a GET request, Last-Modified contains the time at which the current value of the data point was last set. It does not matter whether the update was performed via the REST interface or within a logic group.

If a POST or PUT request fails due to invalid data, the data point is not updated. In this case, Last-Modified continues to contain the time of the last successful update.

Content-Type

The Content-Type header specifies the data format used according to the MIME standard.

Depending on the configuration, for example, the following values are returned:

• JSON: application/json

• CSV: text/csv

• Text: text/plain

Content-Length

The Content-Length header specifies the length of the response body in bytes.

Body (Response Body)

For a successful request, the response body corresponds to the data format configured for the data point.

In the event of an error, the response body is usually empty.

///