 |
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
The handling of the REST interface is described in detail in this Configuration Guide.
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 Web/REST interface page. It contains all commands that are available in the various configurations 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.
It is also possible to query the scheme of each configuration parameter.
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
Access to the REST interface of the router via HTTPS is enabled by default in the latest version of the firmware. Before an access to the REST interface of the router via HTTP is possible, this must be configured accordingly in the Administration menu on the Web/REST interface page. For this, access via HTTP must be activated. The standard ports (80 for HTTP and 443 for HTTPS) can be adjusted. The unencrypted HTTP protocol should only be used, if the connection is encrypted otherwise, e.g. using a VPN. If the firewall is active, an appropriate exceptional rule for HTTP access must be active. If the standard ports are modified, the exceptional rules must be adjusted accordingly.
Authentication
The authentication will be made using Access and Refresh Tokens.
To receive the tokens, a Post request must be made, which will be authorised using a combination of user name and password that is managed in the Administration menu on the Users page.
The Access Token received is used to authenticate further communication via the REST interface.
When the validity of the access token expires (5 minutes), another POST request must be made using the Refresh Token in the authorisation header to obtain new Access and Refresh Tokens for further communication.
The Refresh Token can only be used once to request new tokens and its validity is identical to the time set in the Administration menu on the Web/REST interface page for Auto logout on inactivity.
Logging out of the REST interface will be made with a POST request where both tokens can be used in the authorisation header.
The tokens lose their validity with logout, expiry or a restart of the router.
Example for the request to obtain the tokens:
POST /api/v2_0/auth/login
Username (here insys) and password (here icom) are passed on in the body of the request.
{
"username" : "insys",
"password" : "icom"
}
The following responses are possible upon tis:
400 Bad Request -> body is not correct
401 Unauthorized -> access credentials are not correct
200 OK -> with return of the following body:
{
"access" : "<Access-Token>",
"refresh" : "<Refresh-Token>"
}
Example for the request to renew the tokens:
POST /api/v2_0/auth/refresh (the Refresh Token must be in the authorization header)
The following responses are possible upon tis:
401 Unauthorized -> Refresh Token is not correct
200 OK -> with return of the following body:
{
"access" : "<New-Access-Token>",
"refresh" : "<New-Refresh-Token>"
}
Example for the request to log out from the session:
POST /api/v2_0/auth/logout (one of the two tokens must be in the authorization header)
The following responses are possible upon tis:
401 Unauthorized -> Token is not correct
200 OK
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.1 and the HTTPS port is for example:
192.168.1.1:443/api/v2_0/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 responded 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 Web/REST interface:
GET /api/v2_0/configuration/administration/webinterface
All parameters with their settings are returned in JSON format as response:
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "0",
"https_active": "1",
"http_port": "80",
"https_port": "443",
"https_cert": "device_cert",
"https_key": "device_key",
"session_timeout": "15",
"default_log_reverse": "1",
"default_language": "de",
"default_refresh_interval": "0",
"default_log_lines": "40",
"active_https": "1",
"active_clientauth": "0",
"https_clientauth_ca": "---",
"https_clientauth_crl": "---",
"https_clientauth_group": "readwrite",
"https_ca": "device_ca",
"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 /api/v2_0/configuration/administration/users?profile=Profile_2
All users of profile "Profile_2" are returned in JSON format as response:
{
"profile": {
"name": "Profile_2"
"last_activated": true,
"modified": true
},
"config": {
"unique": {
"password_hashes": "0"
},
"list": [
{
"active": "1",
"username": "insys",
"group": "readwrite",
"index": "user1",
"list_uid": "3e71d7bcbb"
},
{
"active": "1",
"username": "icom",
"group": "readwrite",
"index": "user2",
"list_uid": "bd998ab74a"
},
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3",
"list_uid": "878256c625"
}
]
}
}
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.
If several values are specified - separated by a comma, the filters will be applied following the OR principle (example: "v" : ["value1","value2"]).
Example for outputting all users with the "Read" right:
GET /api/v2_0/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"
"last_activated": true,
"modified": true
},
"list": [
{
"active": "1",
"username": "reader",
"group": "read",
"index": "user3",
"list_uid": "878256c625"
}
]
}
}
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 /api/v2_0/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 /api/v2_0/configuration/administration/users?return_size=1
The number of users is returned in JSON format as response:
{
"profile": {
"name": "Profile"
"last_activated": true,
"modified": true
},
"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 /api/v2_0/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 /api/v2_0/configuration/administration/users
{
"profile": {
"name": "Profile",
"activate": "1"
},
"config": {
"list": [
{
{
"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 /api/v2_0/configuration/wan/wans
{
"config": {
"list": [
{
"sublist": [
{
"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.
The list ID (list_uid) or sublist ID (sublist_uid) is used to identify existing entries when modifying them. A GET request must be issued first to query the existing configuration in order to determine the ID.
Example for modifying the user name of the user "user2" to "newuser" and the rights to read/write::
PUT /api/v2_0/configuration/administration/users
{
"profile": {
"name": "Profile"
},
"config": {
"list": [
{
"username": "newuser",
"group": "readwrite",
"list_uid": "878256c625"
}
]
}
}
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 /api/v2_0/configuration/administration/hostnames
Example for deleting all users with the string "test" in the user name from the profile "Profile_2":
DELETE /api/v2_0/configuration/administration/users?filter={"p":"username","o":"like","v":"test"}&profile=Profile_2
Example for deleting all WAN interfaces:
DELETE /api/v2_0/configuration/wan/wans?delete=interface
Example for deleting the interface "group2" from the WAN chains:
DELETE /api/v2_0/configuration/wan/wans?delete=interface&filter={"p":"interface","o":"eq","v":"group2"}
Scheme requests
The command (HTTP method) GET with the option "?append_scheme=1" is available for querying a configuration scheme including all possible values. This lists all fields and options that are possible and permitted for a resource.
Example for the output of the scheme for the configuration of the e-mail account:
GET /api/v2_0/configuration/events/email_account?append_scheme=1
All configuration options are returned in JSON format as response:
{
{
"profile": {
"name": "Profile",
"last_activated": true,
"modified": false
},
"config": {
"unique": {
"address": "",
"real_name": "",
"server": "",
"encryption": "starttls",
"verify_peer": "",
"verify_host": "",
"port": "25",
"username": "",
"password": ""
}
},
"scheme": {
"parameters": {
"unique": [
{
"name": "address",
"type": "email_addr"
},
{
"name": "real_name",
"type": "string",
"max_len": 100
},
{
"name": "server",
"type": "peer",
"max_len": 100
},
{
"name": "encryption",
"type": "radio",
"items": [
{
"value": "none",
"translate": true,
"label": "none"
},
{
"value": "ssl",
"translate": true,
"label": "ssl"
},
{
"value": "starttls",
"translate": true,
"label": "starttls"
}
]
},
{
"name": "verify_peer",
"type": "checkbox"
},
{
"name": "verify_host",
"type": "checkbox"
},
{
"name": "port",
"type": "int",
"min": 1,
"max": 65535,
"steps": 1
},
{
"name": "username",
"type": "string",
"max_len": 100
},
{
"name": "password",
"type": "passwd",
"max_len": 100
}
]
}
}
}
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 /api/v2_0/status/device_info
All parameters with their values are returned in JSON format as response:
{
"status": {
"list": [
{
"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 /api/v2_0/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 /api/v2_0/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 /api/v2_0/profiles
{
"profiles": [
"name": "Profile",
"last_activated": false,
"modified": false
},
{
"name": "quick_start_profile",
"last_activated": true,
"modified": false
}
]
}
A profile is displayed by the GET call of the respective profile:
GET /api/v2_0/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 /api/v2_0/operation
{
"method" : "manual_action",
"params" : {
"type" : "message",
"options" : {
"message" : "message1"
}
}
}
Example for the manual activation of the Info LED:
POST /api/v2_0/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 Web/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:443/api/v2_0/configuration/administration/webinterface"
{
"profile": {
"name": "Profile"
},
"config": {
"http_active": "0",
"https_active": "1",
"http_port": "80",
"https_port": "443",
"https_cert": "device_cert",
"https_key": "device_key",
"session_timeout": "15",
"default_log_reverse": "1",
"default_language": "de",
"default_refresh_interval": "0",
"default_log_lines": "40",
"active_https": "1",
"active_clientauth": "0",
"https_clientauth_ca": "---",
"https_clientauth_crl": "---",
"https_clientauth_group": "readwrite",
"https_ca": "device_ca",
"log_requests": "0"
}
}
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:443/api/v2_0/configuration/administration/rest"