Administrator: Created page with "==Summary== This page contains some information about details of API commands, examples or use-cases. For more detailed information refer to API. {{ Note|Till version 4...."

2015-12-10T10:22:45Z

Created page with "==Summary== This page contains some information about details of API commands, examples or use-cases. For more detailed information refer to API. {{ Note|Till version 4...."

New page

==Summary==

This page contains some information about details of API commands, examples or use-cases. 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 changed and API logins will be correctly recognised and displayed as API logins. }}

==General information about API sentences==
Communication with router through API is done using '''API sentences''' that consist of '''API command''' and '''attributes'''. API [[API#Queries | queries]] are considered special command attribute, for example '''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====
======CLI 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@CableFree] > 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@CableFree] > 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 attributes======

API has some special attributes, that are not available through CLI, or are not available through CLI directly. These atributes starts with dot. For example .id, that gives identification number of the item, whilst these can be seen in CLI (returned by find) ID is not directly shown with the item.

======API command attributes ======
All attributes of command starts with equals sigh, whilst special case for API attribute to command itself. Like '''.tag''' attribute that is not part of any command, but can be used to identify returned data of command executed.

====Atributes without value====
Commands in RadioOS 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 the 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 RadioOS 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 RadioOS 4.7 it is possible to monitor all API connections to RadioOS under ''/user active'' menu in console (or corresponding menu in winbox). Same way that can be done for telnet, ssh, winbox and webfig logins.

====!fatal====
!fatal can be received only in cases when API is closing connection:
* too many commands are sent to router prior login
* there is error in authentication that is not recoerable
* '''/quit''' command is sent to router. Response looks like this:
>>> /quit

<<< !fatal
<<< session terminated on request

==CLI commands that are not in API==
some commands are not available in API when compared with CLI, these include interactive commands and scripting commands
====Interactive commands====
interactive command examples that will not work in API are:
/system telnet

/system ssh

/tool mac-telnet

====Scripting commands====
Any find command is not supported, use queries and proplist instead
/ip adddress find

Commands that starts with semicolon:
delay error find foreach if local parse
put set toarray toid toip6 tostr typeof
do execute for global len nothing
pick resolve time tobool toip tonum totime while

==API sentence examples==
Examples of use of commands

====Addressing entries====

In some places in API it is possible to address entries using value of ''name'' attribute as attribute ''.id'' value. Some places where ambiguity could arise this feature is not available.

======Examples======

setting interface name to one that already exist:
/interface/set
=.id=ether1
=name=ether2

will result in:

!trap
=category=4
=message=already have device with such name

!done

While adding several entries with same name as static DNS entries is completely legal, addressing entries using ''name'' value for .id is '''NOT'''. Entry with name=example.com address=192.168.88.1 added before.

/ip/dns/static/set
=.id=example.com
=address=3.3.3.3

The result
!trap
=category=0
=message=no such item

====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 v4.x and older====
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

====Ping v5.x and newer ====
it is equivalent of ping available in CLI, but it will give report on averages every time it has result for sent ping.
======Details======
*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.
*Timing results are in form HH:MM:SS.sss (HH - hours; MM - minutes; SS - seconds; sss - miliseconds)

======Example======
/ping
=address=192.168.88.1
=count=2

In this case ping returned after duration*count seconds, where duration was default 1 second.

!re
=host=192.168.88.1
=size=56
=ttl=42
=time=00:00:00.001
=sent=1
=received=1
=packet-loss=0
=min-rtt=00:00:00.001
=avg-rtt=00:00:00.001
=max-rtt=00:00:00.001

!re
=host=192.168.88.1
=size=56
=ttl=42
=time=00:00:00.001
=sent=2
=received=2
=packet-loss=0
=min-rtt=00:00:00.001
=avg-rtt=00:00:00.001
=max-rtt=00:00:00.001

!done

====Cancel tagging====
You may cancel every previously executed task. Note however how cancel behaves with specified tag and without.
======Example without tag======

Command execution.

/ping
=address=google.com

Reply itself.

!re
=host=77.252.2.103
=size=56
=ttl=60
=time=00:00:00.022
=sent=1
=received=1
=packet-loss=0
=min-rtt=00:00:00.022
=avg-rtt=00:00:00.022
=max-rtt=00:00:00.022

!re
=host=77.252.2.103
=size=56
=ttl=60
=time=00:00:00.026
=sent=2
=received=2
=packet-loss=0
=min-rtt=00:00:00.022
=avg-rtt=00:00:00.024
=max-rtt=00:00:00.026

Cancel reply. Notice 2 !done words.

/cancel

!trap
=category=2
=message=interrupted

!done

!done

======Example with specified tag======

Command execution.

/ping
=address=google.com
.tag=22

Reply itself.

!re
=host=5.226.127.144
=size=56
=ttl=61
=time=00:00:00.008
=sent=1
=received=1
=packet-loss=0
=min-rtt=00:00:00.008
=avg-rtt=00:00:00.008
=max-rtt=00:00:00.008
.tag=22

!re
=host=5.226.127.144
=size=56
=ttl=61
=time=00:00:00.025
=sent=2
=received=2
=packet-loss=0
=min-rtt=00:00:00.008
=avg-rtt=00:00:00.016
=max-rtt=00:00:00.025
.tag=22

Cancel command.

/cancel
=tag=22
.tag=1

!trap
=category=2
=message=interrupted
.tag=22

!done
.tag=1

!done
.tag=22

======Canceling with additional errors======

Cancel failed /tool fetch via http. 3 is that tag of /tool/fetch, 7 is a /cancel tag itself.

/cancel
=tag=3
.tag=7

!trap
=category=2
=message=interrupted
.tag=3

!done
.tag=7

!trap
=message=failure: 301 Moved Permanently
.tag=3

!done
.tag=3

======Conclusions======
As you can see in above examples, tagging sentences lets you easilly determine which command have finished.
Please note that every time you cancel
!trap
=category=2
=message=interrupted
is generated.

==See also==

[[API]]

[[Category:API]]

API command notes - Revision history

Administrator: Created page with "==Summary== This page contains some information about details of API commands, examples or use-cases. For more detailed information refer to API. {{ Note|Till version 4...."