Practice of ROS API (1) official translation

Recommended for you: Get network issues from WhatsUp Gold. Not end users.

Summary

Application Programmable Interface (API) allows users to create custom software solutions to communicate with RouterOS to gather information, adjust configuration and manage router. API closely follows syntax from command line interface (CLI). It can be used to create translated or custom configuration tools to aid ease of use running and managing routers with RouterOS.

To use API RouterOS version 3.x or newer is required.

By default API uses port #8728 and service is disabled. More on service management see in corresponding manual section. Corresponding service name is api

It is said that the API interface and the CLI command is similar to Ros, version 3.x and above just support, the default API port 8728 by default, but the service is disabled, the need to manually enable.

Protocol

Communication with router is done by sending sentences to the router and receiving one or more sentences in return. Sentence is sequence of words terminated by zero length word. Word is part of sentence encoded in certain way - encoded length and data. Communication happen by sending sentences to the router and receiving replies to sent sentences. Each sentence sent to router using API should contain command as a first word followed by words in no particular order, end of sentence is marked by zero length word. When router receives full sentence (command word, no or more attribute words and zero length word) it is evaluated and executed, then reply is formed and returned.

Interaction principle by sending statements and receive one or more statements, statement ends with a length of 0 word, encoding the length and the data of two parameters. The parameter order be of no great importance, ROS system receives the command execution and returns a nicely formatted or multiple structure.

API words

Words are part of sentence. Each word has to be encoded in certain way - length of the word followed by word content. Length of the word should be given as count of bytes that are going to be sent.

Word is a part of the sentence, each word must be specified code -- the contents of word + word length. The length is measured using a byte.

Length of the word is encoded as follows:

Value of length # of bytes Encoding
0 <= len <= 0x7F 1 len, lowest byte
0x80 <= len <= 0x3FFF 2 len | 0x8000, two lower bytes
0x4000 <= len <= 0x1FFFFF 3 len | 0xC00000, three lower bytes
0x200000 <= len <= 0xFFFFFFF 4 len | 0xE0000000
len >= 0x10000000 5 0xF0 and len as four bytes


In general words can be described like this <<encoded word length><word content>>. Word content can be separated in 5 parts: command word, attribute word, API attribute word. query word and reply word

Command word

First word in sentence has to be command followed by attribute words and zero length word or terminating word. Name of command word should begin with '/'. Names of commands closely follow CLI, with spaces replaced with '/'. There are commands that are specific to API;

Command word structure in strict order:

API specific commands (specific command):

getall login cancel

Command word concent examples:

/login /ip/address/getall /user/active/listen /interface/vlan/remove /system/reboot

Attribute word

Each command wordhave its own list of attribute words depending on content.

Atribute word structure consists of 5 parts in this order:

  • encoded length
  • content prefix equals sigh - =
  • attribute name
  • separating equals sign - =
  • value of attribute if there is one. It is possible that attribute does not have a value
Icon-note.png

Note: Value can hold multiple equal signs in the value of attribute word since the way word is encoded


Icon-note.png

Note: Value can be empty



Examples without encoded length prefix:

=address=10.0.0.1 =name=iu=c3Eeg =disable-running-check=yes
Icon-warn.png

Warning: Order of attribute words and API parameters is not important and should not be relied on 

The API parameters of the word and API parameters in order to be of no great importance


API attribute word

API attribute word structure is in strict order:

  • encoded length
  • content prefix with dot .
  • attribute name
  • name postfixed with equals =sign
  • attribute value

Currently the only such API attribute is tag.

Icon-note.png

Note: If sentence contain API attribute word tag then each returned sentence in reply from router to that tagged sentence will be tagged with same tag.


Query word

Senteces can have additional query paramteres that restrict their scope. They are explained in detail in separate section.

Example of sentence using query word attributes:

/interface/print ?type=ether ?type=vlan ?#|!


  • Query words begin with '?'.
  • Currently only print command handles query words.
Icon-warn.png

Warning: Order of query words is significant


Recommended from our users: Dynamic Network Monitoring from WhatsUp Gold from IPSwitch. Free Download

Posted by Melody at December 21, 2013 - 8:23 AM