...
| Note |
|---|
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.
...
| Code Block |
|---|
| language | powershell |
|---|
| theme | FadeToGrey |
|---|
|
$ 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
| Code Block |
|---|
|
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:
| Code Block |
|---|
|
POST https://router/rest/interface/print |
...
{"_proplist":"name,type"} |
or a list of strings:
| Code Block |
|---|
|
POST https://router/rest/interface/print |
...
{"_proplist":["name","type"]} |
For example, return address and interface properties from the ip/address list:
| Code Block |
|---|
| language | powershell |
|---|
| theme | FadeToGrey |
|---|
|
$ 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 :
| Code Block |
|---|
|
POST https://router/rest/interface/print |
...
{"_query":["type=ether","type=vlan","#|!"]} |
is equivalent to this API sentence
| Code Block |
|---|
|
/interface/print |
...
...
...
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:
| Code Block |
|---|
|
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:
| Code Block |
|---|
|
POST https://router/rest/tool/bandwidth-test |
...
{"address":"10.0.0.111","duration":10} |
| Note |
|---|
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. |
...
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
| Code Block |
|---|
|
{"error":406,"message":"Not Acceptable","detail":"no such command or directory (remove)"} |