API command notes
Summary
This page contains information about details of API commands, examples. For more detailed information refer to API.
Note: Till version 4.6 including API logins where shown as winbox logins. Since 4.7 this behaviour is changes and API logins will be correctly recognized and displayed as API logins.
General information about API sentences
Communication with router through API happens using API sentences that consist of API command and attributes. API queries are considered special command attribute, same way special API attributes like command tags. In each sentence can only be one command' and many attributes.
Command
API command is command as it is available from CLI (or special API command like 'getall'). Command syntax is derived from CLI and includes CLI path to and command itself.
For example:
/ip address print
API command derived from this CLI command will be:
/ip/address/print
in this case, /ip/address/ is path and print is command itself, but, since print or command on its own does not have meaning, path+command is considered to be command as that determines what to do exactly.
Attributes
Each API sentence can have attributes. Full attribute list can be acquired from CLI using ? or double Tab key.
Example:
First, what command we are going to use? In CLI we will examine /ip address add command.
What attributes command has?
result of ?
[admin@MikroTik] > ip address add Creates new item with specified property values. address -- Local IP address broadcast -- Broadcast address comment -- Short description of the item copy-from -- Item number disabled -- Defines whether item is ignored or used interface -- Interface name netmask -- Network mask network -- Network prefix
result of double Tab
[admin@MikroTik] > ip address add broadcast comment copy-from disabled netmask network address interface
Note: Not all attributes will have full or precise description in CLI, but all attributes will have precise and full description of values accepted by attribute
Building API sentence:
/ip/address/add =address=192.168.88.1/24 =interface=ether1
Result of execution of this command will be IP address added on interface ether1 same as in CLI.
Note: If command in CLI does not have named attribute using ? key you can get required attribute name. Atribute that is not named will appear in between <>
Atributes without value
Commands in RouterOS have attributes that does not have any value set, If these attributes are used it just indicates that they should be used, and value, if any is given will be ignored.
For example, indicate that we will follow IP address changes:
/ip/address/print =follow=
See the equals marks surrounding follow - they should be there as attribute should be between them.
API sentence structure
API sentence should be sent in very specific form. About precise descriptions please see API. If you are not going to write your own API implementations or, you do not understand exactly how it should be created, here is explanation.
- API sentence can consist of several lines (or words)
- when sent to router each word have to have a prefix, that have to be made in a specific way encoding length of the word
- last word in API sentence have to be zero terminated (have to contain byte set to all zeros). Also, if sentence only contains one word, it has to be zero terminated, or else router will wait for further words in that sentence, and all other words will be counted as words from same sentence, not new sentence.
All this boils down to this, where XX is encoded word legth, aaaa is word and 0x00 is terminating zero
single line sentence
XXaaaa0x00
multiple line sentence
XXaaaa XXaaaa0x00
or
XXaaaa XXaaaa XXaaaa0x00
Note: Usually API implementations takes care of encoding word length part and user only have to worry to make sure that correct method/function is used to send words over to router and make sure words make meaningful sentence for execution
Scripting and API
It is possible to access RouterOS scripting global variables through the API if user have enough permissions to read this menu.
/system/script/environment
Users are able to remove or alter value of the variable. Keep in mind, that variable type is automatically determined by scripting engine. Be aware that variable type can change while you are working with it.
Also, no other scripting constructs are available in API (:if, :for etc.)
Note: Through API it is not possible to create new variables
Note: Find command have many constructs that are part of scripting, thus not available through API
API login
since RouterOS 4.7 it is possible to monitor all API connections to RouterOS under /user active menu in console (or corresponding menu in winbox). Same way at is possible to do for winbox, telnet and ssh.
API sentence examples
Examples of use of commands
Monitor-traffic
it is equivalent of CLI /interface monitor-traffic command
Details
- Basic command syntax:
/interface/monitor-traffic =interface=<id1>,<id2>,<id3>
- Output: replies will be sent in succession with in statistics about interface in order of IDs given in command. So, first re! will be for <id1>, second for <id2>
- Duration: command runs until interrupted with /cancel
- planned changes: it is planned to add item identification to replies.
- since interfaces have name field, value from that field can be used to address interface instead of .id
Example
- Command
/interface/monitor-traffic =interface=ether1-Local,ether3-Out
- Return
!re =rx-packets-per-second=4 =rx-drops-per-second=0 =rx-errors-per-second=0 =rx-bits-per-second=8531 =tx-packets-per-second=3 =tx-drops-per-second=0 =tx-errors-per-second=0 =tx-bits-per-second=11266 !re =rx-packets-per-second=8 =rx-drops-per-second=0 =rx-errors-per-second=0 =rx-bits-per-second=14179 =tx-packets-per-second=4 =tx-drops-per-second=0 =tx-errors-per-second=0 =tx-bits-per-second=8591 !re =rx-packets-per-second=4 =rx-drops-per-second=0 =rx-errors-per-second=0 =rx-bits-per-second=2312 =tx-packets-per-second=2 =tx-drops-per-second=0 =tx-errors-per-second=0 =tx-bits-per-second=3039 !re =rx-packets-per-second=5 =rx-drops-per-second=0 =rx-errors-per-second=0 =rx-bits-per-second=4217 =tx-packets-per-second=1 =tx-drops-per-second=0 =tx-errors-per-second=0 =tx-bits-per-second=635
Ping
it is not equivalent of ping available in CLI, but it supports same arguments and working principles are the same. Only difference is in data returned.
Details
- ping in API reports how many successful replies it has received. And can only be used to determine if target host is capable of replying to ICMP requests
- for ease of use it us suggested that it is used with count argument set to some value
- Ping returns only when it is interrupted or reached count limit.
Example
/ping =address=192.168.88.1 =count=3
In this case ping returned after duration*count seconds, where duration was default 1 second.
!done =ret=3