Overview
The term "REST API" generally refers to an API accessed via HTTP protocol at a predefined set of resource oriented URLs.
In RouterOS it is implemented a JSON wrapper interface of the console API. It allows to create, read, update and delete resources and call arbitrary console commands.
To start to use REST API, the www-ssl
service [link to IP services] must be configured and running. When the ssl service is enabled the REST service can be accessed by connecting to https://<routers_IP>/rest
.
The easiest way to start is to use cUrl, wget or any other HTTP client even RouterOS fetch tool [link to fetch].
$ curl -k -u admin: https://10.155.101.214/rest/system/resource [{"architecture-name":"tile","board-name":"CCR1016-12S-1S+", "build-time":"Dec/04/2020 14:19:51","cpu":"tilegx","cpu-count":"16", "cpu-frequency":"1200","cpu-load":"1","free-hdd-space":"83439616", "free-memory":"1503133696","platform":"MikroTik", "total-hdd-space":"134217728","total-memory":"2046820352", "uptime":"2d20h12m20s","version":"7.1beta4 (development)"}]
Authentication
Authentication to the REST API is performed via HTTP Basic Auth. Provide your Username and password are the same as for the console user (by default "admin" with no password).
You have to set up certificates to use secure HTTPS, if self signed certs are used, then CA must be imported to the trusted root. However for testing purposes it is possible to connect insecurely (for cUrl use -k flag, for wget use --no-check-certificate)
JSON format
Server broadly follows ECMA-404 standard, with following notes:
- In JSON replies all object values are encoded as strings, even if the underlying data is a number or a boolean.
- The server also accepts numbers in octal format (begins with 0) and hexadecimal format (begins with 0x). If the numbers are sent in a string format, they are assumed to be in decimal format.
- Numbers with exponents are not supported.
HTTP Methods
Below is a table summarising supported HTTP methods
HTTP Verv | CRUD | Description |
---|---|---|
GET | Read | To get a list of all records. |
PATCH | Update/Modify | To update a single record. |
PUT | Create | To create a new record. |
DELETE | Delete | To delete a single record. |
POST | Universal method to get access to all console commands. |
GET
This method allows to get the list of all records or a single record from the specified menu encoded in the URL.
For example, get all IP addresses (equivalent to ip/address/print
command from the CLI):
$ curl -k -u admin: https://10.155.101.214/rest/ip/address [{".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false", "dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}, {".id":"*2","actual-interface":"ether3","address":"10.0.0.109/24","disabled":"true", "dynamic":"false","interface":"ether3","invalid":"false","network":"10.0.0.0"}]
To return a single record, append the ID at the end of the URL:
$ curl -k -u admin: https://10.155.101.214/rest/ip/address/*1 {".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false", "dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}
If you want to return only specific properties, then append ?fields=
to the end of the URL, followed by a comma separated list of the needed properties. For example, to show only the address and if it's disabled:
$ curl -k -u admin: https://10.155.101.214/rest/ip/address?fields=address,disabled {".id":"*1","actual-interface":"ether2","address":"10.0.0.111/24","disabled":"false", "dynamic":"false","interface":"ether2","invalid":"false","network":"10.0.0.0"}
It is also possible to filter the output, for example, return only valid addresses that belongs to 10.155.101.0 network:
$ curl -k -u admin: "https://10.155.101.214/rest/ip/address?network=10.155.101.0&dynamic=true" [{".id":"*8","actual-interface":"sfp12","address":"10.155.101.214/24","disabled":"false", "dynamic":"true","interface":"sfp12","invalid":"false","network":"10.155.101.0"}]
PATCH
This method is used to update a single record. Set PATCH call body as a JSON object which contains fields and values of the properties to be updated. For example, add a comment:
$ curl -k -u admin: -X PATCH https://10.155.101.214/rest/ip/address/*3 \ --data '{"comment": "test"}' -H "content-type: application/json" {".id":"*3","actual-interface":"dummy","address":"192.168.99.2/24","comment":"test", "disabled":"false","dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.99.0"}
In case of a successful update the server returns the updated object with all it's parameters.
PUT
Method is used to create new records in the menu encoded in the URL. The body should be set as a JSON object containing parameters applied to the newly created record.
In case of a success the server returns the created object with all it's parameters.
Only one resource can be created in a single request.
For example, add IP address to a dummy interface:
$ curl -k -u admin: -X PUT https://10.155.101.214/rest/ip/address \ --data '{"address": "192.168.111.111", "interface": "dummy"}' -H "content-type: application/json" {".id":"*A","actual-interface":"dummy","address":"192.168.111.111/32","disabled":"false", "dynamic":"false","interface":"dummy","invalid":"false","network":"192.168.111.111"}
DELETE
This method is used to delete the record with specified ID from the menu encoded in the URL. If the deletion has been succeeded, the server responds with an empty response. For example, call to delete the record twice, on second call router will return 404 error:
$ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9 $ curl -k -u admin: -X DELETE https://10.155.101.214/rest/ip/address/*9 {"error":404,"message":"Not Found"}
POST
All the API features are available through the POST
method. The command word is encoded in the header and optional parameters are passed in the JSON object with the corresponding fields and values. For example, to change the password of the active user, send
POST https://router/rest/password {"old-password":"old","new-password":"N3w", "confirm-new-password":"N3w"}
REST response is structured similar to API response:
- If the response contains
!re
sentences (records), the JSON reply will contain a list of objects. - If the
!done
sentence contains data, the JSON reply will contain an object with the data. - If there are no records or data in the
!done
sentence, the response will hold an empty list.
There are two special keys: _proplist
and _query
, which are used with the print
command word. Read more about APIs responses, proplists and queries in the API documentation.
Proplist
The _proplist
key is used to create .proplist
attribute word. The values can be a single string with comma separated values:
POST https://router/rest/interface/print {"_proplist":"name,type"}
or a list of strings:
POST https://router/rest/interface/print {"_proplist":["name","type"]}
For example, return address and interface properties from the ip/address list:
$ curl -k -u admin: -X POST https://10.155.101.214/rest/ip/address/print\ --data '{"_proplist": ["address","interface"]}' -H "content-type: application/json" [{"address":"192.168.99.2/24","interface":"dummy"}, {"address":"172.16.5.1/24","interface":"sfpplus1"}, {"address":"172.16.6.1/24","interface":"sfp2"}, {"address":"172.16.7.1/24","interface":"sfp3"}, {"address":"10.155.101.214/24","interface":"sfp12"}, {"address":"192.168.111.111/32","interface":"dummy"}]
Query
The _query
key is used to create a query stack. The value is a list of query words. For example this POST request :
POST https://router/rest/interface/print {"_query":["type=ether","type=vlan","#|!"]}
is equivalent to this API sentence
/interface/print ?type=ether ?type=vlan ?#|!
Timeout
If the command runs indefinitely, it will timeout and connection will be closed with an error. To avoid timeout errors, add a parameter that would sufficiently limit the command execution time. For example, to limit number of pings, add count parameter:
POST https://router/rest/ping {"address":"10.0.0.111","count":4}
Another example is bandwidth test tool, which can be limited by providing run duration:
POST https://router/rest/tool/bandwidth-test {"address":"10.0.0.111","duration":10}
Timeout is not affected by the parameters passed to the commands. If the bandwidth test is set to run for an hour, it will terminate early and return an error message.
Errors
The success or failure of the API calls are indicated in the HTTP status code. If case of failure (status code 400 or larger), the body of the response contains a JSON object with the error code, a description of the error and optional error details. For example, trying to delete an interface will return
{"error":406,"message":"Not Acceptable","detail":"no such command or directory (remove)"}