Date: Fri, 29 Mar 2024 06:50:45 +0200 (EET) Message-ID: <1516554334.127.1711687845446@help.mikrotik.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_126_522412253.1711687845443" ------=_Part_126_522412253.1711687845443 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Application Programmable Interface (API) allows users to create custom s= oftware solutions to communicate with RouterOS to gather information, adjus= t the configuration, and manage the router. API closely follows syntax from= the command-line interface (CLI). It can be used to create translated or c= ustom configuration tools to aid ease of use in running and managing router= s with RouterOS.
API service must be enabled before trying to establish the API connectio= n. By default, API uses TCP:8728 and TCP:8729 (secure).&n= bsp;
API-SSL service is capable of working in two modes - with and without a = certificate. In the case no certificate is used in /ip service set= tings then an anonymous Diffie-Hellman cipher has to be used to establish a= connection. If a certificate is in use, a TLS session can be established.<= /p>
Communication with the router is done by sending sentences and receiving= one or more sentences in return. A sentence is a sequence of words termina= ted by zero-length words. Word is part of a sentence encoded in a certain w= ay - encoded length and data. Communication happens by sending sentences to= the router and receiving replies to sent sentences. Each sentence sent to = the router using API should contain a command as a first word followed by w= ords in no particular order, the end of the sentence is marked by a zero-le= ngth word. When the router receives a full sentence (command word, no or mo= re attribute words, and zero-length word) it is evaluated and executed, the= n a reply is formed and returned.
Words are part of a sentence. Each word has to be encoded in a certain w= ay - the length of the word followed by the word content. The length of the= word should be given as a count of bytes that are going to be sent.
The length of the word is encoded as follows:
Value of length | # of bytes | Encoding |
---|---|---|
0 <=3D len <=3D 0x7F | 1 | len, lowest byte |
0x80 <=3D len <=3D 0x3FFF | 2 | len | 0x8000, two lower bytes |
0x4000 <=3D len <=3D 0x1FFFFF | 3 | len | 0xC00000, three lower bytes |
0x200000 <=3D len <=3D 0xFFFFFFF | 4 | len | 0xE0000000 |
len >=3D 0x10000000 | 5 | 0xF0 and len as four bytes |
In general, words can be described like this <<encode= d word length><word content>>. Word content= em> can be separated into 5 parts: command word, attribut= e word, API attribut= e word. query word, and reply word
The first word in the sentence has to be a command followed by attribute= words and a zero-length word or terminating word. The name of the command = word should begin with '/'. Names of commands closely follow CLI, with spac= es replaced with '/'. Some commands are specific to API;
Command word structure in the strict order:
API-specific commands:
login cancel
Command word content examples:
/login
/user/active/listen
/interface/vlan/remove
/system/reboot
Each command word has its list of attribute words= depending on content.
Attribute word structure consists of 5 parts in this order:
Value can hold multiple equal signs in the value of an attr= ibute word since the way the word is encoded.
Value can be empty.
Examples without encoded length prefix:
=3Daddress=3D10.0.0.1
=3Dname=3Diu=3Dc3Eeg
=3Ddisable-running-check=3Dyes
Order of attribute words and API parameters is not important and should = not be relied on
API attribute word structure is in the strict order:
Currently, the only such API attribute is the tag.
If the sentence contains an API attribute word tag then each re= turned sentence in reply from the router to that tagged sentence will be ta= gged with the same tag.
Sentences can have additional query parameters that restrict their scope= . A detailed explanation is in the query s= ection.
Example of a sentence using query word attributes:
/interface/print ?type=3Dether ?type=3Dvlan ?#|!
The order of query words is significant
It is only sent by the router in response to the full sentence received = from the client.
API sentence is the main object of communication using API.
Zero-length word terminates the sentence. If it is not provided= router will not start to evaluate sent words and will consider all the inp= ut as part of the same sentence.
Note: that each command and response ends with an empty= word.
Login method post-v6.43:
/login |
=3Dname=3Dadmin |
=3Dpassword=3D |
!done |
The print command accepts qu= ery words that limit the set of returned sentences.
Query | Description |
---|---|
?name | pushes 'true' if an item has a value of property= name, 'false' if it does not. |
?-name | pushes 'true' if an item does not have a value o= f property name, 'false' otherwise. |
?name=3Dx = ?=3Dname=3Dx |
pushes 'true' if the property name has = a value equal to x, 'false' otherwise. |
?<name=3Dx | pushes 'true' if the property name has = a value less than x, 'false' otherwise. |
?>name=3Dx | pushes 'true' if the property name has = a value greater than x, 'false' otherwise. |
?#operations | applies operations to the values in the stack.=
=20
|
Regular expressions are not supported in API, so do not try to send a qu= ery with the ~ symbol
Examples:
/interface/print ?type=3Dether ?type=3Dvlan ?#|
/ip/route/print ?>comment=3D
The print command can return= OID values for properties that are available in SNMP.
In the console, OID values can be seen by running the 'print oid' comman= d. In API, these properties have a name that ends with ".oid", and can be r= etrieved by adding their name to the value of '.proplist'. An example:
/system/resource/print= td> |
=3D.proplist=3Duptime,cp= u-load,uptime.oid,cpu-load.oid |
!re |
=3Duptime=3D01:22:53 |
=3Dcpu-load=3D0 |
=3Duptime.oid=3D.1.3.6.1.= 2.1.1.3.0 |
=3Dcpu-load.oid=3D.1.3.6.= 1.2.1.25.3.3.1.2.1 |
!done |
When for some reason API sentence fails trap is sent in return accompani= ed by a message attribute and on some occasions ca= tegory argument.
When an API sentence fails, some generic message or message from the use= d internal process is returned to give more details about the failure
<<= ;< /ip/address/add=20 <<< =3Daddress=3D192.168.88.1=20 <<< =3Dinterface=3Dasdf <<<=20 >>> !trap=20 >>> =3Dcategory=3D1=20 >>> =3Dmessage=3Dinput does not match any value of interface
if it is a general error, it is categorized and the error category is re= turned. possible values for this attribute are
/system/package/getall= td> |
!re |
=3D.id=3D*5802 |
=3Ddisabled=3Dno |
=3Dname=3Drouteros-x86 |
=3Dversion=3D3.0beta2 |
=3Dbuild-time=3Doct/18/20= 06 16:24:41 |
=3Dscheduled=3D |
!re |
=3D.id=3D*5805 |
=3Ddisabled=3Dno |
=3Dname=3Dsystem |
=3Dversion=3D3.0beta2 |
=3Dbuild-time=3Doct/18/20= 06 17:20:46 |
=3Dscheduled=3D |
... more !re sentenc= es ... |
!re |
=3D.id=3D*5902 |
=3Ddisabled=3Dno |
=3Dname=3Dadvanced-tools<= /td> |
=3Dversion=3D3.0beta2 |
=3Dbuild-time=3Doct/18/20= 06 17:20:49 |
=3Dscheduled=3D |
!done |
/user/active/listen |
!re |
=3D.id=3D*68 |
=3Dradius=3Dno |
=3Dwhen=3Doct/24/2006 08:= 40:42 |
=3Dname=3Dadmin |
=3Daddress=3D0.0.0.0 |
=3Dvia=3Dconsole |
!re |
=3D.id=3D*68 |
=3D.dead=3Dyes |
... more !re sentenc= es ... |
/login |
!done |
=3Dret=3D856780b7411eefd3= abadee2058c149a3 |
/login |
=3Dname=3Dadmin |
=3Dresponse=3D005062f7a5e= f124d34675bf3e81f56c556 |
!done |
-- first s= tart listening for interface changes (tag is 2) |
/interface/listen |
.tag=3D2 |
-- disable= interface (tag is 3) |
/interface/set |
=3Ddisabled=3Dyes |
=3D.id=3Dether1 |
.tag=3D3 |
-- this is= done for disable command (tag 3) |
!done |
.tag=3D3 |
-- enable = interface (tag is 4) |
/interface/set |
=3Ddisabled=3Dno |
=3D.id=3Dether1 |
.tag=3D4 |
-- this up= date is generated by a change made by the first set command (tag 3) |
!re |
=3D.id=3D*1 |
=3Ddisabled=3Dyes |
=3Ddynamic=3Dno |
=3Drunning=3Dno |
=3Dname=3Dether1 |
=3Dmtu=3D1500 |
=3Dtype=3Dether |
.tag=3D2 |
-- this is= done for enable command (tag 4) |
!done |
.tag=3D4 |
-- get int= erface list (tag is 5) |
/interface/getall |
.tag=3D5 |
-- this up= date is generated by a change made by the second set command (tag 4)= td> |
!re |
=3D.id=3D*1 |
=3Ddisabled=3Dno |
=3Ddynamic=3Dno |
=3Drunning=3Dyes |
=3Dname=3Dether1 |
=3Dmtu=3D1500 |
=3Dtype=3Dether |
.tag=3D2 |
-- these a= re replies to getall command (tag 5) |
!re |
=3D.id=3D*1 |
=3Ddisabled=3Dno |
=3Ddynamic=3Dno |
=3Drunning=3Dyes |
=3Dname=3Dether1 |
=3Dmtu=3D1500 |
=3Dtype=3Dether |
.tag=3D5 |
!re |
=3D.id=3D*2 |
=3Ddisabled=3Dno |
=3Ddynamic=3Dno |
=3Drunning=3Dyes |
=3Dname=3Dether2 |
=3Dmtu=3D1500 |
=3Dtype=3Dether |
.tag=3D5 |
-- here in= terface getall ends (tag 5) |
!done |
.tag=3D5 |
-- stop li= stening - request to cancel command with tag 2, cancel itself uses tag 7 |
/cancel |
=3Dtag=3D2 |
.tag=3D7 |
-- listen = command is interrupted (tag 2) |
!trap |
=3Dcategory=3D2 |
=3Dmessage=3Dinterrupted<= /td> |
.tag=3D2 |
-- cancel = command is finished (tag 7) |
!done |
.tag=3D7 |
-- listen = command is finished (tag 2) |
!done |
.tag=3D2 |
A simple API client in Pyt= hon3
Example output:
debian@= localhost:~/api-test$ ./api.py 10.0.0.1 admin '' <<< /login <<<=20 >>> !done >>> =3Dret=3D93b438ec9b80057c06dd9fe67d56aa9a >>>=20 <<< /login <<< =3Dname=3Dadmin <<< =3Dresponse=3D00e134102a9d330dd7b1849fedfea3cb57 <<<=20 >>> !done >>>=20 /user/getall <<< /user/getall <<<=20 >>> !re >>> =3D.id=3D*1 >>> =3Ddisabled=3Dno >>> =3Dname=3Dadmin >>> =3Dgroup=3Dfull >>> =3Daddress=3D0.0.0.0/0 >>> =3Dnetmask=3D0.0.0.0 >>>=20 >>> !done >>>
API implementations in different languages, provided by different source= s. They are not ordered in any particular order.