 |
Online Help icom Data Suite |
REST interface
REST stands for Representational State Transfer and provides an interface for configuration, status query and execution of manual actions of the application via HTTP and HTTPS protocol.
The following commands (HTTP methods) are available for editing the resources (parameters or entries):
- GET: Reading out a resource
- POST: Adding a resource
- PUT: Modifying a resource
- DELETE: Deleting a resource
Activating the REST interface
Before an access to the REST interface of the application via HTTP or HTTPS is possible, this must be configured accordingly in the Administration menu on the REST interface page. For this, access via HTTP and/or HTTPS must be activated and, if the firewall in the router is active, an appropriate exceptional rule must be present and active. The unencrypted HTTP protocol should only be used, if the connection is encrypted otherwise, e.g. using a VPN.
Addressing
Addressing takes place using the IP address of the icom Data Suite, the port for REST access and the path to the parameters. The path to the parameters is also structured in sections here as in the CLI. Addressing for the parameters of the REST interface in an application with the IP address 192.168.1.10 and the HTTPS port is for example:
192.168.1.10:9091/configuration/administration/rest
The path starts always with a certain directory, e.g. /configuration/ for configuration parameters, followed by the respective sections.
Syntax
The syntax of the available commands can easy be found out using the auto-complete function of the CLI. See this example for the proceeding to determine the command syntax
Configuration
The commands (HTTP methods) GET, POST, PUT and DELETE are available for reading out or modifying the configuration. For configuration parameters, the path always starts with /configuration/.
Reading out parameters (GET)
Parameters are read out using the HTTP method GET.
Example for reading out the parameters of the REST interface:
GET /configuration/administration/rest
All parameters with their settings are returned in JSON format as response:
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "1",
"https_active": "1",
"http_port": "9090",
"https_port": "9091",
"https_cert": "app_cert",
"https_key": "app_key"
}
}
The first section of the response references the profile, the second the configuration with the individual parameters.
Specifying the profile in the GET command
Without a specification, the GET command will always refer to the running profile. If the parameters of another profile are to be read out, the command must be complemented by the profile specification.
Example for reading out theusers of profile "Profile_2":
GET /configuration/administration/rest?profile=Profile_2
All users of profile "Profile_2" are returned in JSON format as response:
{
"profile": {
"name": "Profile_2"
},
"config": {
"user": [
{
"active": "1",
"username": "insys",
"group": "readwrite",
"index": "user1"
},
{
"active": "1",
"username": "icom",
"group": "readwrite",
"index": "user2"
},
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Filtering a list in the GET command
In case of a list, the GET command will return all entries. In order to see only the desired entries in the response, the command can be passed with a filter. The parameter that is to be filtered, an operator for the filter function and the desired value of the parameter are specified in a JSON array for the filter:
{
"p" : "parameter",
"o" : "operator",
"v" : "value"
}
The parameter is one of the configuration parameters in the list entry.
The operator is either eq (the parameter must have exactly this value) or like (the parameter must contain the value regardless of capitalisation).
The value is the value to which the parameter value must comply or that must be contained in it.
Example for outputting all users with the "Read" right:
GET /configuration/administration/users?filter={"p":"group","o":"eq","v":"read"}
All parameters of all users with the "Read" right are returned in JSON format as response:
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3"
}
]
}
}
Multiple filters are also possible. Then, all filters will be combined using a logical AND, i.e. all filter criteria must be met that an entry will be displayed.
Example for outputting all users with the "Read" right and the string "ic" in the user name:
GET /configuration/administration/users?filter=[{"p":"group","o":"eq","v":"read"},{"p":"username","o":"like","v":"ic"}]
Querying the number of list entries using the GET command
In order to query the number of entries of a list, the command will be complemented by the parameter return_size; here, it is important to pass a value with the parameter whose figure is not important.
Example for outputting the number of existing users:
GET /configuration/administration/users?return_size=1
The number of users is returned in JSON format as response:
{
"profile": {
"name": "Profile"
},
"config": {
"list_size": 3
}
}
If a filer is handed over with this, only the number of list entries will be put out that meet the filter criteria.
Adding parameters (POST)
The HTTP method POST is used to add entries to lists. The entry must not have a list index for this since the entry will be appended to the end of the list.
Example for adding the new user "newuser" with read rights to the profile "Profile" and simultaneous activation of the modified profile:
POST /configuration/administration/users
{
"profile": {
"name": "Profile",
"activate": "1"
},
"config": {
"user": [
{
"active": "1",
"username": "newuser",
"group": "read"
}
]
}
}
Above example adds the new user to the profile "Profile". The parameter "name": "Profile" specifies the profile to which the modifications are applied. If it will be left out, the user will be added to the running profile. The parameter "activate": "1" activates the modified profile. If it will be left out, the profile will only be modified. but not activated. If modifications are only to be applied to the running profile and this shall not be activated, the complete profile section can be left out.
Some application functions require lists within lists.
Example for adding a new "Holding register" data point with the description "test" and the format "Unsigned Integer 32" to the data point list of the Modbus device "mdbDev1":
POST /configuration/datapoints/modbus
{
"config": {
"device": [
{
"name": "mdbDev1",
"datapoint": [
{
"datapoint_active": "1",
"datapoint_description": "test",
"datapoint_type": "holding_register",
"datapoint_register": "",
"datapoint_bit": "",
"datapoint_format": "uint32"
}
]
}
]
}
}
Modifying parameters (POST)
The HTTP method PUT is used to modify existing entries in lists.
Example for modifying the rights of the user "icom" from read to read/write::
PUT /configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"username": "newuser",
"group": "readwrite",
"index": "user1"
}
]
}
}
The list identifier, here the parameter "index" is imperative for specifying the entry to be modified.
Deleting parameters (DELETE)
The HTTP method DELETE is used to delete complete lists or existing entries from lists.
Example for deleting all digital outputs:
DELETE configuration/datapoints/digital_ios/outputs
Example for deleting all users with the string "test" in the user name from the profile "Profile_2":
DELETE configuration/administration/users?filter={"p":"username","o":"like","v":"test"}&profile=Profile_2
Example for deleting all Modbus data points:
DELETE configuration/datapoints/modbus?delete=datapoint
Example for deleting all Modbus data points with the type "Holding register":
DELETE configuration/datapoints/modbus?delete=datapoint&filter={"p":"datapoint_type","o":"eq","v":"holding_register"}
Status queries
The command (HTTP method) GET is available for querying status information. For querying status information, the path always starts with /status/.
Example for reading out the current values of the data points:
GET /status/values
All data points with their values are returned in JSON format as response:
{
"status": {
"values": [
{
"name": "input1",
"value": "1"
},
{
"name": "input2",
"value": "0"
},
{
"name": "input3",
"value": "0"
}
]
}
}
Example for reading out the current values of certain data points:
GET /status/values?status=input1,input3
Only the data points specified in the call with their values are returned in JSON format as response:
{
"status": {
"values": [
{
"name": "input1",
"value": "1"
},
{
"name": "input3",
"value": "0"
}
]
}
}
Displaying log files and profiles
The command (HTTP method) GET is available for displaying log files and profiles. For displaying log files and profiles, the path always starts with /download/.
Log files
An overview of all log files stored in the application is returned by a GET call of the log file list:
GET download/log?list_files=1
{
"log_files": [
"configd/current",
"configd/log-2018-02-20-09:45:39.bz2",
"httpd/current",
"httpd/log-2018-02-20-09:45:39.bz2",
...
]
}
A log file is displayed by the GET call of the respective file:
GET download/log?log_file=configd/current
2018-04-19 07:44:46 [configd] Started
2018-04-19 07:44:50 [configd] reading m3 config again
2018-04-19 07:44:51 [configd] M3 config read
2018-04-19 08:25:11 [configd] Profile 'Profile' activated
2018-04-19 08:25:11 [configd] cleaning persistent database
Profiles
An overview of all profiles stored in the application is returned by a GET call of the profile list:
GET download/profiles?list_files=1
{
"profiles": [
"Profile",
"Profile_2"
]
}
A profile is displayed by the GET call of the respective profile:
GET download/profiles?profile=Profile
Since the profile has a binary format, it must be stored accordingly.
Debugging and triggering manual actions
The command (HTTP method) POST is available for debugging and triggering manual actions. For debugging and triggering manual actions, the path always starts with /operation/.
It is possible to execute manual actions for debugging purposes.
Example for the manual dispatch of the message "sms1":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "sms1"
}
}
}
Example for the manual setting of the analogue flag 1 to the value "13":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "analog",
"options" : {
"datapoint" : "flag1",
"change" : "set_to",
"set" : "to_value",
"value" : "13"
}
}
}
See this example for the proceeding to determine the command syntax