...
API service must be enabled before trying to establish the API connection. By default, API uses TCP:8728 and TCP:8729 (secure).
API-ssl service is capable to work in two modes - with and without a certificate. In the case no certificate is used in /ip service settings then anonymous Diffie-Hellman cipher have to be used to establish connection. If certificate is in use, TLS session can be established.
Protocol
Communication with the router is done by sending sentences and receiving one or more sentences in return. A sentence is a sequence of words terminated by zero-length words. Word is part of a sentence encoded in a certain way - 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 words in no particular order, the end of the sentence is marked by a zero-length word. When the router receives a full sentence (command word, no or more attribute words, and zero-length word) it is evaluated and executed, then a reply is formed and returned.
...
| /login |
| !done |
| =ret=856780b7411eefd3abadee2058c149a3 |
| /login |
| =name=admin |
| =response=005062f7a5ef124d34675bf3e81f56c556 |
| !done |
| -- first start listening for interface changes (tag is 2) |
| /interface/listen |
| .tag=2 |
| -- disable interface (tag is 3) |
| /interface/set |
| =disabled=yes |
| =.id=ether1 |
| .tag=3 |
| -- this is done for disable command (tag 3) |
| !done |
| .tag=3 |
| -- enable interface (tag is 4) |
| /interface/set |
| =disabled=no |
| =.id=ether1 |
| .tag=4 |
| -- this update is generated by change made by first set command (tag 3) |
| !re |
| =.id=*1 |
| =disabled=yes |
| =dynamic=no |
| =running=no |
| =name=ether1 |
| =mtu=1500 |
| =type=ether |
| .tag=2 |
| -- this is done for enable command (tag 4) |
| !done |
| .tag=4 |
| -- get interface list (tag is 5) |
| /interface/getall |
| .tag=5 |
| -- this update is generated by change made by second set command (tag 4) |
| !re |
| =.id=*1 |
| =disabled=no |
| =dynamic=no |
| =running=yes |
| =name=ether1 |
| =mtu=1500 |
| =type=ether |
| .tag=2 |
| -- these are replies to getall command (tag 5) |
| !re |
| =.id=*1 |
| =disabled=no |
| =dynamic=no |
| =running=yes |
| =name=ether1 |
| =mtu=1500 |
| =type=ether |
| .tag=5 |
| !re |
| =.id=*2 |
| =disabled=no |
| =dynamic=no |
| =running=yes |
| =name=ether2 |
| =mtu=1500 |
| =type=ether |
| .tag=5 |
| -- here interface getall ends (tag 5) |
| !done |
| .tag=5 |
| -- stop listening - request to cancel command with tag 2, cancel itself uses tag 7 |
| /cancel |
| =tag=2 |
| .tag=7 |
| -- listen command is interrupted (tag 2) |
| !trap |
| =category=2 |
| =message=interrupted |
| .tag=2 |
| -- cancel command is finished (tag 7) |
| !done |
| .tag=7 |
| -- listen command is finished (tag 2) |
| !done |
| .tag=2 |
Example client
A simple API client in Python3
Example output:
| Code Block | ||||
|---|---|---|---|---|
| ||||
debian@localhost:~/api-test$ ./api.py 10.0.0.1 admin '' <<< /login <<< >>> !done >>> =ret=93b438ec9b80057c06dd9fe67d56aa9a >>> <<< /login <<< =name=admin <<< =response=00e134102a9d330dd7b1849fedfea3cb57 <<< >>> !done >>> /user/getall <<< /user/getall <<< >>> !re >>> =.id=*1 >>> =disabled=no >>> =name=admin >>> =group=full >>> =address=0.0.0.0/0 >>> =netmask=0.0.0.0 >>> >>> !done >>> |
...