Manual:API

This document describes the operation of MikroTik RouterOS API for RouterOS3.

Enabling and Connecting

• Default API port is 8728. By default API is disabled
• Enable API /ip service enable api
• Now you can initiate TCP connection to the API port of the router

Protocol

• Protocol stream is formatted as a sequence of words.
• Each word is encoded as lenght, followed by that many bytes of content.
• Words are grouped into sentences. End of sentence is terminated by zero length word.
• Lenght is encoded as follows:

Value of length	Number 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

• Although this scheme allows encoding of length up to 0x7FFFFFFFF, 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.

Short description of API sentences

• Empty sentences are ignored.
• Sentences are processed after receiving terminating zero length word.
• There is a limit on number and size of sentences client can send before it has logged in.
• Commands
  • First word is name of command. Examples:

/login
/ip/address/getall
/user/active/listen
/interface/vlan/remove
/system/reboot

• • Names of commands closely follow console, with spaces replaced by '/'. There are commands that are specific to API, like 'getall' or 'login'.
  • Name of command should begin with '/'.
  • Next, command arguments can be specified. Examples:

=address=10.0.0.1
=name=iu=c3Eeg
=disable-running-check=yes

• • Command argument should begin with '=' followed by name of argument, followed by another '=', followed by value of argument.
  • Agrument value can be empty and can contain '='.
  • First word of reply begins with '!'.
  • Each command generates at least one reply (if connection does not get terminated).
  • Last reply for every command is reply that has first word '!done'.
  • Errors and exceptional conditions begin with '!trap'.
  • Data replies begin with '!re'

Initial login

/login

!done

=ret=ebddd18303a54111e2dea05a92ab46b4

/login

=name=admin

=response=001ea726ed53ae38520c8334f82d44c9f2

!done

1. First, clients sends /login command.
2. Reply contains =ret=challenge argument.
3. Client sends second /login command, with =name=username and =response=response.
4. In case of error, reply contains =ret=error message.
5. In case of successful login client can start to issue commands.

Command examples

1. /system/package/getall
2. Note that replies contain =.id=Item internal number property, that is not available in console. Names of properties that are API specific begin with dot.

/system/package/getall

!re =.id=*5802 =disabled=no =name=routeros-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