API command notes: Difference between revisions

From MikroTik Wiki
Jump to navigation Jump to search
Line 4: Line 4:


==General information about API sentences==
==General information about API sentences==
Communication with router through API happens using API sentences that consist of API command and attributes. API [[API#Queries | 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 <> }}


==API sentences==
==API sentences==

Revision as of 08:53, 5 March 2010

Summary

This page contains information about details of API commands, examples

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
Icon-note.png

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.

Icon-note.png

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 <>


API sentences

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

See also

API