Manual:API
Summary
Application Programmable Interface (API) allows users to create custom software solutions to communicate with RadioOS to gather information, adjust configuration and manage router. API closely follows syntax from command line interface (CLI). It can be used to create translated or custom configuration tools to aid ease of use running and managing routers with RadioOS.
To use API RadioOS version 3.x or newer is required.
By default API uses port #8728 and service is disabled. More on service management see in corresponding manual section. Corresponding service name is api
Protocol
Communication with router is done by sending sentences to the router and receiving one or more sentences in return. Sentence is sequence of words terminated by zero length word. Word is part of sentence encoded in certain way - encoded length and data. Communication happen by sending sentences to the router and receiving replies to sent sentences. Each sentence sent to router using API should contain command as a first word followed by words in no particular order, end of sentence is marked by zero length word. When router receives full sentence (command word, no or more attribute words and zero length word) it is evaluated and executed, then reply is formed and returned.
API words
Words are part of sentence. Each word has to be encoded in certain way - length of the word followed by word content. Length of the word should be given as count of bytes that are going to be sent.
Length of the word is encoded as follows:
Value of length | # of bytes | Encoding |
---|---|---|
0 <= len <= 0x7F | 1 | len, lowest byte |
0x80 <= len <= 0x3FFF | 2 | len | 0x8000, two lower bytes |
0x4000 <= len <= 0x1FFFFF | 3 | len | 0xC00000, three lower bytes |
0x200000 <= len <= 0xFFFFFFF | 4 | len | 0xE0000000 |
len >= 0x10000000 | 5 | 0xF0 and len as four bytes |
- Each word is encoded as length, followed by that many bytes of content;
- Words are grouped into sentences. End of sentence is terminated by zero length word;
- Scheme allows encoding of length up to 0x7FFFFFFFFF, only four byte length is supported;
- Bytes of len are sent most significant first (network order);
- If first byte of word is >= 0xF8, then it is a reserved control byte. After receiving unknown control byte API client cannot proceed, because it cannot know how to interpret following bytes;
- Currently control bytes are not used;
In general words can be described like this <<encoded word length><word content>>. Word content can be separated in 5 parts: command word, attribute word, API attribute word. query word and reply word
Command word
First word in sentence has to be command followed by attribute words and zero length word or terminating word. Name of command word should begin with '/'. Names of commands closely follow CLI, with spaces replaced with '/'. There are commands that are specific to API;
Command word structure in strict order:
- encoded length
- content prefix /
- CLI converted command
API specific commands:
login cancel
Command word concent examples:
/login
/user/active/listen
/interface/vlan/remove
/system/reboot
Attribute word
Each command wordhave its own list of attribute words depending on content.
Atribute word structure consists of 5 parts in this order:
- encoded length
- content prefix equals sigh - =
- attribute name
- separating equals sign - =
- value of attribute if there is one. It is possible that attribute does not have a value
Note: Value can hold multiple equal signs in the value of attribute word since the way word is encoded
Examples without encoded length prefix:
=address=10.0.0.1
=name=iu=c3Eeg
=disable-running-check=yes
API attribute word
API attribute word structure is in strict order:
- encoded length
- content prefix with dot .
- attribute name
- name postfixed with equals =sign
- attribute value
Currently the only such API attribute is tag.
Note: If sentence contain API attribute word tag then each returned sentence in reply from router to that tagged sentence will be tagged with same tag.
Query word
Senteces can have additional query paramteres that restrict their scope. They are explained in detail in separate section.
Example of sentence using query word attributes:
/interface/print ?type=ether ?type=vlan ?#|!
- Query words begin with '?'.
- Currently only print command handles query words.
Reply word
It is sent only by the router. It is only sent in response to full sentence send by the client.
- First word of reply begins with '!';
- Each sentence sent generates at least one reply (if connection does not get terminated);
- Last reply for every sentence is reply that has first word !done;
- Errors and exceptional conditions begin with !trap;
- Data replies begin with !re
- If API connection is closed, RadioOS sends !fatal with reason as reply and then closes the connection;
API sentences
API sentence is main object of communication using API.
- Empty sentences are ignored.
- Sentence is processed after receiving zero length word.
- There is a limit on number and size of sentences client can send before it has logged in.
- Order of attribute words should not be relied on. As order and count is changeable by .proplist attribute.
- Sentence structure is as follows:
- First word should contain command word;
- Should contain zero length word to terminate the sentence;
- Can contain none or several attribute words. There is no particular order at what attribute words has to be sent in the sentence, order is not important for attribute words;
- Can contain none or several query words. Order of query words in the sentence is important.
Note: Zero length word terminates the sentence. If it is not provided router will not start to evaluate sent words and will consider all the input as part of the same sentence.
Initial login
/login |
!done |
=ret=ebddd18303a54111e2dea05a92ab46b4 |
/login |
=name=admin |
=response=001ea726ed53ae38520c8334f82d44c9f2 |
!done |
- First, clients sends /login command.
- Reply contains =ret=challenge argument.
- Client sends second /login command, with =name=username and =response=response.
- In case of error, reply contains =ret=error message.
- In case of successful login client can start to issue commands.
Tags
- It is possible to run several commands simultaneously, without waiting for previous one to complete. If API client is doing this and needs to differentiate command responses, it can use 'tag' API parameter in command sentences.
- If you include 'tag' parameter with non-empty value in command sentence, then 'tag' parameter with exactly the same value will be included in all responses generated by this command.
- If you do not include 'tag' parameter or it's value is empty, then all responses for this command will not have 'tag' parameter.
Command description
- /cancel
- optional argument: =tag=tag of command to cancel, without it cancels all running commands
- does not cancel itself
- all canceled commands are interruped and in the usual case generate '!trap' and '!done' responses
- please note that /cancel is separate command and can have it's own unique '.tag' parameter, that is not related to '=tag' argument of this command
- listen
- listen command is avaliable where console print command is available, but it does not have expected effect everywhere (i.e. may not work)
- !re sentences are generated as something changes in particular item list
- when item is deleted or dissapears in any other way, the '!re' sentence includes value '=.dead=yes'
- This command does not terminate. To terminate it use /cancel command.
- getall
- getall command is available where console print command is available. Since version 3.21 getall is an alias for print.
- replies contain =.id=Item internal number property.
- print
- API print command differs from the console counterpart in the following ways:
- where argument is not supported. Items can be filtered using query words (see below).
- .proplist argument is a comma separated list of property names that should be included for the returned items.
- returned items may have additional properties.
- order of returned properties is not defined.
- if list contains duplicate entries, handling of such entries is not defined.
- if propery is present in .proplist, but absent from the item, then that item does not have this property value (?name will evaluate to false for that item).
- if .proplist is absent, all properties are included as requested by print command, even those that have slow access time (such as file contents and perfomance counters). Thus use of .proplist is encouraged. Omission of .proplist may have high perfomance penalty if =detail= argument is set.
- API print command differs from the console counterpart in the following ways:
Queries
print command accepts query words that limit set of returned sentences. This feature is available since RadioOS 3.21.
- Query words begin with '?'.
- Order of query words is significant. Query is evaluated starting from the first word.
- Query is evaluated for each item in the list. If query succeeds, item is processed, if query fails, item is ignored.
- Query is evaluated using a stack of boolean values. Initially stack contains infinite amount of 'true' values. At the end of evaluation, if stack contains at least one 'false' value, query fails.
- Query words operate according to the following rules:
Query | Desciption |
---|---|
?name | pushes 'true' if item has value of property name, 'false' if it does not. |
?-name | pushes 'true' if item does not have value of property name, 'false' otherwise. |
?name=x ?=name=x |
pushes 'true' if property name has value equal to x, 'false' otherwise. |
?<name=x | pushes 'true' if property name has value less than x, 'false' otherwise. |
?>name=x | pushes 'true' if property name has value greater than x, 'false' otherwise. |
?#operations | applies operations to the values in the stack.
|
Examples:
- Get all ethernet and VLAN interfaces:
/interface/print ?type=ether ?type=vlan ?#|
- Get all routes that have non-empty comment:
/ip/route/print ?>comment=
OID
print command can return OID values for properties that are available in SNMP. This feature appeared in 3.23 version.
In console, OID values can be seen by running 'print oid' command. In API, these properties have name that ends with ".oid", and can be retrieved by adding their name to the value of '.proplist'. An example:
/system/resource/print |
=.proplist=uptime,cpu-load,uptime.oid,cpu-load.oid |
!re |
=uptime=01:22:53 |
=cpu-load=0 |
=uptime.oid=.1.3.6.1.2.1.1.3.0 |
=cpu-load.oid=.1.3.6.1.2.1.25.3.3.1.2.1 |
!done |
!trap
When for some reason API sentence fails trap is sent in return accompanied with message attribute and on some occasions category argument.
message
When API sentence fails some generic message or message from used internal process is return to give more details about failure
<<< /ip/address/add <<< =address=192.168.88.1 <<< =interface=asdf <<< >>> !trap >>> =category=1 >>> =message=input does not match any value of interface
category
if it is a general error, it is categorized and error category is returned. possible values for this attribute are
- 0 - missing item or command
- 1 - argument value failure
- 2 - execution of command interrupted
- 3 - scripting related failure
- 4 - general failure
- 5 - API related failure
- 6 - TTY related failure
- 7 - value generated with :return command
Command examples
/system/package/getall
/system/package/getall |
!re |
=.id=*5802 |
=disabled=no |
=name=RadioOS-x86 |
=version=3.0beta2 |
=build-time=oct/18/2006 16:24:41 |
=scheduled= |
!re |
=.id=*5805 |
=disabled=no |
=name=system |
=version=3.0beta2 |
=build-time=oct/18/2006 17:20:46 |
=scheduled= |
... more !re sentences ... |
!re |
=.id=*5902 |
=disabled=no |
=name=advanced-tools |
=version=3.0beta2 |
=build-time=oct/18/2006 17:20:49 |
=scheduled= |
!done |
/user/active/listen
/user/active/listen |
!re |
=.id=*68 |
=radius=no |
=when=oct/24/2006 08:40:42 |
=name=admin |
=address=0.0.0.0 |
=via=console |
!re |
=.id=*68 |
=.dead=yes |
... more !re sentences ... |
/cancel, simultaneous commands
/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
- this is simple API client in Python2
- example for Python3
- usage: api.py ip-address username password
- after that type words from keyboard, terminating them with newline
- Since empty word terminates sentence, you should press enter twice after last word before sentence will be sent to router.
#!/usr/bin/python import sys, posix, time, md5, binascii, socket, select class ApiRos: "RadioOS api" def __init__(self, sk): self.sk = sk self.currenttag = 0 def login(self, username, pwd): for repl, attrs in self.talk(["/login"]): chal = binascii.unhexlify(attrs['=ret']) md = md5.new() md.update('\x00') md.update(pwd) md.update(chal) self.talk(["/login", "=name=" + username, "=response=00" + binascii.hexlify(md.digest())]) def talk(self, words): if self.writeSentence(words) == 0: return r = [] while 1: i = self.readSentence(); if len(i) == 0: continue reply = i[0] attrs = {} for w in i[1:]: j = w.find('=', 1) if (j == -1): attrs[w] = '' else: attrs[w[:j]] = w[j+1:] r.append((reply, attrs)) if reply == '!done': return r def writeSentence(self, words): ret = 0 for w in words: self.writeWord(w) ret += 1 self.writeWord('') return ret def readSentence(self): r = [] while 1: w = self.readWord() if w == '': return r r.append(w) def writeWord(self, w): print "<<< " + w self.writeLen(len(w)) self.writeStr(w) def readWord(self): ret = self.readStr(self.readLen()) print ">>> " + ret return ret def writeLen(self, l): if l < 0x80: self.writeStr(chr(l)) elif l < 0x4000: l |= 0x8000 self.writeStr(chr((l >> 8) & 0xFF)) self.writeStr(chr(l & 0xFF)) elif l < 0x200000: l |= 0xC00000 self.writeStr(chr((l >> 16) & 0xFF)) self.writeStr(chr((l >> 8) & 0xFF)) self.writeStr(chr(l & 0xFF)) elif l < 0x10000000: l |= 0xE0000000 self.writeStr(chr((l >> 24) & 0xFF)) self.writeStr(chr((l >> 16) & 0xFF)) self.writeStr(chr((l >> 8) & 0xFF)) self.writeStr(chr(l & 0xFF)) else: self.writeStr(chr(0xF0)) self.writeStr(chr((l >> 24) & 0xFF)) self.writeStr(chr((l >> 16) & 0xFF)) self.writeStr(chr((l >> 8) & 0xFF)) self.writeStr(chr(l & 0xFF)) def readLen(self): c = ord(self.readStr(1)) if (c & 0x80) == 0x00: pass elif (c & 0xC0) == 0x80: c &= ~0xC0 c <<= 8 c += ord(self.readStr(1)) elif (c & 0xE0) == 0xC0: c &= ~0xE0 c <<= 8 c += ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) elif (c & 0xF0) == 0xE0: c &= ~0xF0 c <<= 8 c += ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) elif (c & 0xF8) == 0xF0: c = ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) c <<= 8 c += ord(self.readStr(1)) return c def writeStr(self, str): n = 0; while n < len(str): r = self.sk.send(str[n:]) if r == 0: raise RuntimeError, "connection closed by remote end" n += r def readStr(self, length): ret = '' while len(ret) < length: s = self.sk.recv(length - len(ret)) if s == '': raise RuntimeError, "connection closed by remote end" ret += s return ret def main(): s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) s.connect((sys.argv[1], 8728)) apiros = ApiRos(s); apiros.login(sys.argv[2], sys.argv[3]); inputsentence = [] while 1: r = select.select([s, sys.stdin], [], [], None) if s in r[0]: # something to read in socket, read sentence x = apiros.readSentence() if sys.stdin in r[0]: # read line from input and strip off newline l = sys.stdin.readline() l = l[:-1] # if empty line, send sentence and start with new # otherwise append to input sentence if l == '': apiros.writeSentence(inputsentence) inputsentence = [] else: inputsentence.append(l) if __name__ == '__main__': main()
Example run:
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 >>>
See also
API examples
API implementations in different languages, provided by different sources. They are not ordered in any particular order.
in the Wiki
- in Flash Actionscript 3
- in Ruby on rails
- in VB .NET
- in java see java client on github from Gideon LeGrange
- in NodeJS
- Python3
- in RUST GPL v3
External sources
- in .NET (C#) high-level api solution
- additional info by danikf
- in Erlang by Valery Comtihon