ROS API的实践（1） 官方说明翻译

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

大体意思是说API接口和CLI命令比较类似，需要Ros 3.x版本及以上才支持，默认API使用8728端口，但是默认其服务是禁用的，需要手动启用。

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.

交互原理是通过发送语句并接受一个或者多个语句进行的，语句结尾是一个0长度的word，编码采用 长度和数据 两个参数进行。参数顺序无关紧要，ROS系统接收到命令后执行并返回格式化好的一个或者多个结构。

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是句子的一个部分，每个word必须通过特定的编码——word的内容 + word的长度。长度是使用 字节 来度量的。

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

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:

• encoded length
• content prefix /
• CLI converted command

API specific commands（特定的命令）：

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

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

Note: Value can be empty

Examples without encoded length prefix:

=address=10.0.0.1

=name=iu=c3Eeg

=disable-running-check=yes

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

API参数的word及API参数顺序无关紧要

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.

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.

Warning: Order of query words is significant