System information

Manual:System/Time
157
References
[1] http:/ / www. twinsun. com/ tz/ tz-link. htm
Manual:API
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
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.
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.
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
•• Each word is encoded as length, followed by that many bytes of content;
•• Words are grouped into sentences. End of sentence is terminated by zero length word;
• Scheme allows encoding of length up to 0x7FFFFFFFFF, only four byte length is supported;
• Bytes of len are sent most significant first (network order);
• If first byte of word is >= 0xF8, then it is a reserved control byte. After receiving unknown control byte API
client cannot proceed, because it cannot know how to interpret following bytes;
•• Currently control bytes are not used;
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