ROS REST - RouterOS REST API

Translate: Indonesia

Introduction

Make an HTTP request (REST API) from Node.js to RouterOS. The REST API is a new feature, it's starting to be available in RouterOS v7.1beta4.

Getting Started

Prerequisites

• Use RouterOS v7.1beta4 or newer.

• Install Node.js.

• Enable www-ssl service (Winbox: IP > Services).

• Install CA certificate, if only used on local network (for testing) create self-signed certificate, run following command in Winbox Terminal (more):

  /certificate
  add name=ca-template days-valid=3650 common-name=your.server.url key-usage=key-cert-sign,crl-sign
  add name=server-template days-valid=3650 common-name=your.server.url
  
  /certificate
  sign ca-template name=root-ca
  :delay 3s
  sign ca=root-ca server-template name=server
  :delay 3s
  
  /certificate
  set root-ca trusted=yes
  set server trusted=yes
  
  /ip service
  set www-ssl certificate=server disabled=no

Install

To install ROS REST, run the following command:

npm:

npm i ros-rest

or, yarn:

yarn add ros-rest

Configuration

const rosRest = require('ros-rest');

const clientRosRest = rosRest({
  host: '192.168.100.32',
  user: 'user',
  password: 'password',
  port: 443, // default 443
  secure: false, // default false
});

The rosRest function expects a RouterOS credential object and returns the method which we will discuss below.

Here's a list of expected object properties for rosRest:

| Property | Type | Default | Description | | ---------- | ------- | ------- | ------------------------------------------------------------------------------ | | host | string | - | host RouterOS | | port | number | 443 | port www-sssl service RouterOS | | user | string | - | user to login to RouterOS | | password | string | - | password to login to RouterOS | | secure | boolean | false | is the certificate validated by a publicly trusted certificate authority (CA)? |

Note: If the certificate is self-signed set secure to false (default). If the certificate is validated by a certificate authority (CA) and RouterOS is accessible over a public network, set secure to true for security.

Method

Here's a list of the methods we can use that the rosRest function returns:

| HTTP | RouterOS | ROS REST | Description | | ------ | -------- | -------- | ------------------------------------------------------- | | GET | print | print | To get the records. | | PUT | add | add | To update a single record. | | PATCH | set | set | To create a new record. | | DELETE | remove | remove | To delete a single record. | | POST | | command | Universal method to get access to all console commands. |

Learn more: RouteOS REST API Documentation

All methods return a Promise, we can handle it using then/catch or try/catch.

then/catch:

clientRosRest
  .print('ip/address')
  .then((res) => {
    console.log('result:', res);
  })
  .catch((err) => {
    console.log('error:', err);
  });

try/catch:

const fetchRouterOS = async () => {
  try {
    const res = await clientRosRest.print('ip/address');
    console.log('result:', res);
  } catch (err) {
    console.log('error:', err);
  }
};

fetchRouterOS();

For error handling and response schema, see the Axios documentation:

• Error Handling
• Response Schema

print

Example of retrieving all IP Address data (Winbox: IP > Address):

clientRosRest.print('ip/address');

Fetch by id, ether, or by a property containing a specific value:

clientRosRest.print('ip/address/*2');
clientRosRest.print('ip/address/ether1');
clientRosRest.print('ip/address?network=10.155.101.0&dynamic=true');

If we only need certain properties, use .proplist:

clientRosRest.print('ip/address?.proplist=address,disabled');

add

Example of adding a new IP Address:

clientRosRest.add('ip/address', {
  address: '192.168.10.1/24',
  network: '192.168.10.1',
  interface: 'ether2',
  comment: 'test ROS REST',
});

set

Example of updating an IP Address comment that has id *13:

clientRosRest.set('ip/address/*13', {
  comment: 'update comment test ROS REST',
});

remove

Example of deleting IP Address which has id *13:

clientRosRest.remove('ip/address/*13');

command

All API features are available via the command method.

clientRosRest.command('interface/print', {
  '.proplist': ['name', 'type'],
});

// or

clientRosRest.command('interface/print', {
  '.proplist': 'name,type',
});

Contributing

Contributions, issues and feature requests are welcome. Feel free to check issues page if you want to contribute.