Working with the 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 the HTTP and HTTPS protocol.

Benefits of the REST interface: The HTTP(S) REST interface permits to configure the router automated or retrieve values using scripts.

You’ll find an example for reading out, adding, modifying and deleting configurations via the REST interface using the Postman app and the web-based tool Swagger in the following. It shall communicate how to determine the syntax for command and transmitted configuration information (payload) using different tools and how to transmit it to the router.

The REST interface is supported by all INSYS routers with icom OS from firmware 4.3. The tools mentioned are only examples and serve as guide for dealing with the REST interface using external tools.

The icom Data Suite available for the INSYS routers features a REST interface as well. The handling is analogous to the REST interface of the router described here.

The documentation of the REST API contains all commands that are available in the different configurations and equipment variants of the router. Not all contained commands are supported by your router. Router and REST API documentation must have the same firmware revision.

1. Situation

The following configuration steps are to be made using the REST interface:

Retrieving the currently configured users of a router
Adding a new user
Modifying the configuration of this user
Deleting the newly added user

2. Solution

The full documentation of the REST API will be downloaded from the router in form of a JSON file according to the OpenAPI Specification 3.0. This JSON file will be opened in a tool, such as the Swagger Editor or Postman, to determine the syntax for command transmission. The adjusted configuration commands will then be transmitted to the router using this tools or a cURL command.
Ensure that you have access to the web interface of the router.

2.1. Activating the REST interface and downloading the REST API documentation

Open web interface of the router using a browser: 192.168.1.1 ^[1]
Check the checkbox Activate REST interface via HTTPS in the Administration → REST interface menu and click on Save settings.
Click on REST API documentation (OpenAPI as JSON) and download the REST API documentation to the computer.
Click on the blinking gear in the title bar () to activate the profile.

2.2. Adding a firewall rule

If a firewall is active on the router, an exception rule must be addd that permits access to the REST interface.

In the Netfilter → IP filter menu, ass a new firewall rule () and edit this ():
- Description: Local access to REST interface via HTTPS
- Packet direction: INPUT
- IP version: select used IP version
- Protocol: TCP
- Input interface: check all interfaces over which the REST interface is to be accessed
- Destination port: 9091
Click on Save settings.
Click on the blinking gear in the title bar () to activate the profile.

2.3. Determining the REST syntax and transmitting the configuration commands to the router

REST API tools such as Postman and the Swagger Editor provide a very convenient way for this. Configuration commands can also be issued in a command line using cURL.

2.3.1. Postman

The Postman app is a useful tool for communicating with the router via the REST interface. The following describes how to import the REST API documentation of the router in the Postman app, enter the credentials for the REST interface and verify the environment variables for the communication with the router.

Download the Postman app and install it.
Open the Postman app
Click on the Import button in the My Workspace field on the top left (or the menu File → Import…) and open the downloaded REST API documentation.
Select Documentation under Link this collection as and click on the Import button.
Click the Close button to finish the import.
The documentation of the REST API of the router will be displayed as a collection.
Hover over the new collection, click on View more actions and select Edit.
Change in the field of the icom OS - REST API to the Authorization tab, select the type Type Basic Auth and enter the Username and the associated Password of the user. The user must exist in the Administration → User menu of the routers with read/write privileges.
Click on Update to store the credentials in the collection.
Change to the Variables tab and verify the stored variables for protocol (HTTP or HTTPS), IP address of the router and port for HTTP/HTTPS access. The default values of the router have been entered here with above imported REST API documentation. If these have been modified, they need to be adjusted here. ^[2]

2.3.1.1. Querying the user configuration

The HTTP command required for reading out resources (parameters or entries) is GET. The syntax of the command is described in the documentation of the REST API.

Navigate in the collection icom OS - REST API to configuration → administration → users and click on the command GET.
Disable in the Query Params section the checkboxes for profile, return_size and filter.
Click on the Send button to send the GET command to the router.

The reply appears in the lower part of the Postman app window in JSON format with the status code 200 OK. It contains the user configuration of the router. Compare the configuration in the web interface of the router in the Administration menu on the User user page with this.
cg en m3 rest interface pm 05
cg en m3 rest interface 02

2.3.1.2. Adding a user

The HTTP command required for adding resources (parameters or entries) is POST. The syntax of the command is described in the documentation of the REST API.

Navigate in the collection icom OS - REST API to configuration → administration → users and click on the command POST.
Change to the Body tab and adjust the payload in JSON format as follows or copy it.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

Click on the Send button to send the POST command to the router.

With this command, a new active user with the user name CGTestUser, the password icom and the user group Read will be added to the profile Profile, which will not be activated subsequently.

The reply appears in the lower part of the Postman app window in JSON format with the status code 201 Created. Above transmitted configuration will be displayed again.
cg en m3 rest interface pm 06

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the newly added user. ^[3]
cg en m3 rest interface 03

2.3.1.3. Modifying the configuration of a user

The HTTP command required for adding resources (parameters or entries) is PUT. The syntax of the command is described in the documentation of the REST API.

Navigate in the collection icom OS - REST API to configuration → administration → users and click on the command PUT.
Change to the Body tab and adjust the payload in JSON format as follows or copy it.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "group": "readwrite",
        "index": "user2"
      }
    ]
  }
}

Click on the Send button to send the PUT command to the router.

With this command, the user group of the user with the index user2 in the profile Profile will be set to Read/Write. This will change the user group of above added user. The index of the user is displayed, if the GET command for querying the user configuration is executed again after adding.

The reply appears in the lower part of the Postman app window in JSON format with the status code 200 OK.
cg en m3 rest interface pm 07

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the changed user group. ^[3]
cg en m3 rest interface 04

2.3.1.4. Deleting a User

The HTTP command required for adding resources (parameters or entries) is DELETE. The syntax of the command is described in the documentation of the REST API.

Navigate in the collection icom OS - REST API to configuration → administration → users and click on the command DEL.
Enter on the Params tab under Query Params the value Profile for the query parameter profile. This deletes all users that meet the filter criteria from the profile Profile.
Enter the the value {"p":"username","o":"like","v":"test"} for the query parameter filter. This deletes all users from the specified (or last activated, if no profile is specified) profile, whose user name ("p":"username") contains ("o":"like") the string test ("v":"test").

Each filter consists of three parameters:
"p" : "parameter to be filtered"
"o" : "operator to be used for the filter, either "eq" (equal) for an exact match or "like" (similar) if the specified string is to be contained only"
"v" : "value that is to be searched in the parameter according to the operator"

Click on the Send button to send the DELETE command to the router.

The reply appears in the lower part of the Postman app window in JSON format with the status code 200 OK.
cg en m3 rest interface pm 08

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the user deleted again now. ^[3]
cg en m3 rest interface 02

2.3.1.5. Triggering actions manually

The router permits to execute a variety of actions, such as time server synchronisation, restart, message dispatch or setting an output. Actions are triggered with the occurrence of an event, but can also be triggered manually. In the present example, the Info LED on the router is to be activated.

The HTTP command required for triggering actions manually is POST. Unfortunately, it is not that straightforward to determine the syntax of the JSON body for manual actions in Postman. However, the necessary syntax can be determined using the CLI. Refer to the Rest interface → Debugging and triggering manual actions as well as Determining the command syntax for CLI and REST interface in the Online Help of the router for this.

Navigate in the collection icom OS - REST API zu operation and click on the command POST.
hange to the Body tab and adjust the payload in JSON format as follows or copy it.

{
    "method" : "manual_action",
    "params" : {
        "type" : "info_led",
        "options" : {
            "info_led" : "on"
        }
    }
}

Click on the Send button to send the POST command to the router.

This command activates the Info LED on the router. It is deactivated with the value off for the parameter info_led in the same way.

The reply appears in the lower part of the Postman app window in JSON format with the status code 201 Created.
cg en m3 rest interface pm 09

Also observe the LED on the router.

2.3.2. Swagger Editor

The Swagger Editor is a useful online tool for getting an overview of all existing commands with their associated options and determining the syntax of commands for the transmission via the REST interface. It does not require an installation. The following describes how to import the REST API documentation of the router in the Swagger Editor, determine the syntax of a command and transmit the command in a command line using cURL to the router.

Open the Swagger Editor in a browser.
Click in the Swagger Editor on File → Import file and open above downloaded REST API documentation.
Click on Authorize and enter your credentials:
- Username: insys (default)
- Password: icom (default)
Click on Authorize and then on Close.

You have stored your credentials in the Swagger Editor with this. They will then be integrated encrypted into the generated cURL commands.

The left field contains the REST API documentation in JSON format and it is shown in the right field clearly legible and broken up into the individual commands. The order of the commands corresponds to the order of the menus in the web interface of the router. It contains all commands that are available in the different configurations and equipment variants of the router. Not all contained commands are supported by your router.

2.3.2.1. Querying the user configuration

The HTTP command required for reading out resources (parameters or entries) is GET. The syntax of the command is described in the documentation of the REST API.

Navigate in the right field of the Swagger Editor to the Administration section and click there under /configuration/administration/users on the GET command to open the detailed description of the command.
Click on Try it out to be able to generate the command.
Delete the default values of the possible query parameters profile and return_size and click on Execute to generate the command.
Copy the command displayed in the Curl section.
Open a Terminal window (under Windows: → → Command prompt), paste the copied command ^[4], append the option -k to the command and press the enter key. ^[5]

The response is displayed in the Terminal window in JSON format. It contains the user configuration of the router. Compare the configuration in the web interface of the router in the Administration menu on the User user page with this.
cg en m3 rest interface 02

2.3.2.2. Adding a user

The HTTP command required for adding resources (parameters or entries) is POST. The syntax of the command is described in the documentation of the REST API.

Navigate in the right field of the Swagger Editor to the Administration section and click there under /configuration/administration/users on the POST command to open the detailed description of the command.
Click on Try it out to be able to generate the command.
Modify the payload in JSON format in the Request body section as follows or paste it there and click on Execute to generate the command.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "active": "1",
        "username": "CGTestUser",
        "password": "icom",
        "group": "read"
      }
    ]
  }
}

Copy the command displayed in the Curl section.
Open a Terminal window, paste the copied command ^[4], append the option -k to the command and press the enter key. ^[5]

The response is displayed in the Terminal window in JSON format. It contains the transmitted configuration.

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the changed user group.
cg en m3 rest interface 03

2.3.2.3. Modifying the configuration of a user

The HTTP command required for adding resources (parameters or entries) is PUT. The syntax of the command is described in the documentation of the REST API.

Navigate in the right field of the Swagger Editor to the Administration section and click there under /configuration/administration/users on the PUT command to open the detailed description of the command.
Click on Try it out to be able to generate the command.
Modify the payload in JSON format in the Request body section as follows or paste it there and click on Execute to generate the command.

{
  "profile": {
    "name": "Profile",
    "activate": "0"
  },
  "config": {
    "user": [
      {
        "group": "readwrite",
        "index": "user2"
      }
    ]
  }
}

Copy the command displayed in the Curl section.
Open a Terminal window, paste the copied command ^[4], append the option -k to the command and press the enter key. ^[5]

No special response is displayed in the Terminal window.

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the changed user group.
cg en m3 rest interface 04

2.3.2.4. Deleting a User

The HTTP command required for adding resources (parameters or entries) is DELETE. The syntax of the command is described in the documentation of the REST API.

Navigate in the right field of the Swagger Editor to the Administration section and click there under /configuration/administration/users on the DELETE command to open the detailed description of the command.
Click on Try it out to be able to generate the command.
Enter the value Profile for the query parameter profile in the Parameters section. This deletes all users that meet the filter criteria from the profile Profile.
Enter the the value {"p":"username","o":"like","v":"test"} for the query parameter filter. This deletes all users from the specified (or last activated, if no profile is specified) profile, whose user name ("p":"username") contains ("o":"like") the string test ("v":"test").

Click on Execute to generate the command.
Copy the command displayed in the Curl section.
Open a Terminal window, paste the copied command ^[4], append the option -k to the command and press the enter key. ^[5]

No special response is displayed in the Terminal window.

Compare the configuration in the web interface of the router in the Administration menu on the User user page with the user deleted again now.
cg en m3 rest interface 02

2.3.3. Triggering actions manually

The HTTP command required for triggering actions manually is POST. The syntax of the command is described in the documentation of the REST API.

Navigate in the right field of the Swagger Editor to the Operation section and click there under /operation on the POST command to open the detailed description of the command.
Click on Try it out to be able to generate the command.
Modify the payload in JSON format in the Request body section as follows or paste it there and click on Execute to generate the command.

{
    "method" : "manual_action",
    "params" : {
        "type" : "info_led",
        "options" : {
            "info_led" : "on"
        }
    }
}

Copy the command displayed in the Curl section.
Open a Terminal window, paste the copied command ^[4], append the option -k to the command and press the enter key. ^[5]

This command activates the Info LED on the router. It is deactivated with the value off for the parameter info_led in the same way.

No special response is displayed in the Terminal window. Also observe the LED on the router.

The individual parameters for the different actions are available in the REST API in the Schemas section in the Swagger Editor.
cg en m3 rest interface se 17

3. Troubleshooting

In case of problems with the cURL syntax, it might be helpful to use the option -v (verbose) to facilitate troubleshooting.
In case an error related to an untrusted certificate chain is displayed when executing a cURL command copied from the Swagger Editor, it might be possible that the cURL option -k has not been appended to the command, which avoids a verification of the certificate.
Depending on operating system, it might be possible the the cURL command generated in the Swagger Editor cannot be processed directly in the Terminal. In this case, modify it as follows:
- Copy command into text editor
- Remove single quotes around the cURL command (e.g. GET)
- Replace single quotes around the parameters by double quotes
- Remove line breaks
- Remove unnecessary blanks
- Remove unnecessary backslashes (\)

Back to the Configuration Guides for icom OS Smart Devices

Back to overview

1. Login depending on configuration; default for past firmware versions: User name: insys, Password: icom

2. A wrong default port for HTTPS (9090 instead of 9091) has been entered in an earlier version of the REST API documentation (firmware 4.3) and must be adjusted here.

3. In order to see the addition, the running profile on the router must be the same than the profile to which the user has been added, here Profile

4. It might be possible that the generated cURL command must be edited; refer to Troubleshooting

5. The cURL option -k avoids a verification of the certificate.