REST API
There are a number of possibilities to change system settings via the REST API (HTTP), to start processes or to read out information from the system.
Authentication
Each request requires authentication. For this, you need the login name and password of a user with the user right " Administrator" or "Administration via REST".
The authentication can either be done via Basic Authentication (i.e. in the header). Alternatively, the user data can be passed in the URL with &user=myuser&passwd=mypassword.
If LDAP is activated, you can specify a REST fallback user in addition to the general fallback user.
Important note: Authentication works differently for HTTP profiles (see there) and there is a further option for the system monitoring (see there).
Swagger/OpenAPI
The following URL provides a Swagger/OpenAPI interface description of the REST API in JSON and YAML format (see documentation there).
|
https://<URL or IP of Integration Server>/dw/spi/oas/v1/api |
|
Entry |
Reference |
|
System Monitoring |
Refers to sections |
|
MQTT |
Refers to MQTT connections . |
|
Remote Control |
Refers to sections |
|
Partner Management |
Refers to section Partners (REST API). |
|
Statemachine (Workflow) |
Refers to section Using Workflows via HTTP (REST API). |
|
(HTTP Input Agents) |
In addition, corresponding interface descriptions can also be provided for individual HTTP Input Agents. Note: The URL here is different from the other entries, see description in the Input Agent. |
View
(1) An authentication is necessary (see section above).
(2) Click here.
(3) Select the values for the parameters.
(4) Click here. After that you will see the request and the response below.
External tools
As external software you can use Postman, for example. You can find instructions there and on many other pages.
Building your own REST interface/API
A profile with an "HTTP" Input Agent can act as a REST interface. The request suffix is stored in the system variable MSG_CALL_HTTP_PATH_DATA . If you evaluate this variable, you can perform different actions. In a simple case, for example, you could add two values passed by request parameter if the request suffix is add or subtract them if the request suffix is "subtract". Of course, you can also trigger any other (and more complex) action. For example, trigger different workflows or subsequent profiles or call sub-profiles. This allows you to build an HTTP profile as a dispatcher for your own REST API, but you can optionally build any number of such HTTP profiles.