 |
Online Help |
REST interface
REST stands for Representational State Transfer and provides an interface for configuration, status query and execution of manual actions of the router 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
Documentation of the REST API
The REST API (programming interface) is documented in a JSON file according to the OpenAPI specification 3.0. The file can be downloaded in the Administration menu on the REST interface page. It contains all commands that are available in the various configurationen and equipment variants of the router. Not all contained commands are supported by your router.
Syntax
The syntax of the available commands can easy be determined using the REST API documentation file by opening it with an OpenAPI tool, such as Swagger or Postman.
See the Command reference page for this.
Alternatively, it can be found out using the auto-complete function of the CLI.
See this example for the proceeding to determine the command syntax.
Activating the REST interface
Before an access to the REST interface of the router 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 is active, an appropriate exceptional rule must be present and active. The standard ports (9090 for HTTP and 9091 for HTTPS) can be adjusted. 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 router, 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 a router 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.
Response codes
All REST commands are responced with HTTP status codes. The following codes are returned for the parameters described here to indicate a successful transmission of the REST command:
- GET: 200 OK
- POST: 201 CREATED
- PUT: 200 OK
- DELETE: 200 OK
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": "device_cert",
"https_key": "device_key",
"log_requests": "0"
}
}
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 specification of the name of the profile.
Example for reading out the users of profile "Profile_2":
GET /configuration/administration/users?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 filter is handed over with this, only the number of list entries will be put out that meet the filter criteria.
Example for outputting the number of existing 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":"st"}]&return_size=1
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 router functions require lists within lists.
Example for adding a new interface "net3" with a connection check interval of 13 minutes and the fall-back WAN chain "wan2" to the WAN chain "wan1":
POST /configuration/wan/wans
{
"config": {
"wan_chain": [
{
"name": "wan1",
"interface": [
{
"interface": "net3",
"check_interval": "13",
"check_fail_wan": "wan2",
"check_type": "none"
}
]
}
]
}
}
Modifying parameters (PUT)
The HTTP method PUT is used to modify existing entries in lists.
Example for modifying the user name of the user "user2" to "newuser" and the rights to read/write::
PUT /configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"user": [
{
"username": "newuser",
"group": "readwrite",
"index": "user2"
}
]
}
}
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. If no filters are used, all entries will be deleted. Filters permit a selective deletion of certain entries.
Example for deleting all host names:
DELETE /configuration/administration/hostnames
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 WAN interfaces:
DELETE /configuration/wan/wans?delete=interface
Example for deleting the interface "group2" from the WAN chains:
DELETE /configuration/wan/wans?delete=interface&filter={"p":"interface","o":"eq","v":"group2"}
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 device info:
GET /status/device_info
All parameters with their values are returned in JSON format as response:
{
"status": {
"slot": [
{
"board_type": "M3CPU",
"hardware_features": "0x00",
"hardware_version": "3",
"firmware_version": "4.3",
"serial_number": "12345678"
},
{
"board_type": "M3PWL",
"hardware_features": "0x04",
"hardware_version": "2",
"firmware_version": "",
"serial_number": ""
},
]
}
}
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 router 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 router 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 "message1":
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "message1"
}
}
}
Example for the manual activation of the Info LED:
POST /operation
{
"method" : "manual_action",
"params" : {
"type" : "info_led",
"options" : {
"info_led" : "on"
}
}
}
See this example for the proceeding to determine the command syntax
Example for querying the configuration using a cURL command
The following cURL command can be used to read the configuration of the REST interface in the Administration menu for example:
curl -X GET -H "Content-type: application/json" -H "Accept: application/json" -u "insys:icom" "http://192.168.1.10:9090/configuration/administration/rest"
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "1",
"https_active": "1",
"http_port": "9090",
"https_port": "9091",
"https_cert": "app_cert",
"https_key": "app_key"
}
}
In order to determine the cURL syntax, refer to the Command reference page and the Configuration Guide linked there.
Tip: In case of problems with the cURL syntax, it might be helpful to use the option '-v' (verbose) to facilitate troubleshooting:
curl -v -X GET -H "Content-type: application/json" -H "Accept: application/json" -u "insys:icom" "http://192.168.1.10:9090/configuration/administration/rest"