Skip to content

Latest commit

 

History

History
201 lines (143 loc) · 5.53 KB

README.md

File metadata and controls

201 lines (143 loc) · 5.53 KB
Raw

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:

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.