RESTAPI-MIKROTIK
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 RESTAPI-MIKROTIK, run the following command:
npm:
npm i restapi-mikrotik
or, yarn:
yarn add ros-rest
Configuration
const rosRest = require('ros-rest');
const clientRosRest = rosRest({
host: '10.10.10.1',
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
tofalse
(default). If the certificate is validated by a certificate authority (CA) and RouterOS is accessible over a public network, setsecure
totrue
for security.
Method
Here's a list of the methods we can use that the rosRest
function returns:
HTTP | RouterOS | ROS REST | Description |
---|---|---|---|
GET | 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:
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.