Overview
Basics
The Unimus API is a JSON based RESTfull API. It utilizes common HTTP methods such as GET, POST, PATCH and DELETE in order to identify
action you want to perform.
When submitting a request that contains a body you must include a header for Content-type that specifies application/json.
API changes since version 1
Security
Every request has to include Authorization header following Bearer scheme as shown below.
Authorization: Bearer <token>
Log into your local Unimus instance and navigate to User management > API tokens section to create new token.
Returned data format
All responses are returned as JSON. If a response can ever contain a single item it will be formatted as follow:
{ "data":{ "someKey":"someValue", "anotherKey":"anotherValue" } }
Multi-item responses are paginated automatically. The maximum amount of items that can be returned in a single query is 50, default is 20. You may specify the number of items to be returned in response by appending a query parameter size.
You may specify the page you wish to view by appending a parameter page, default is 0. Multi-item responses are formatted as follow:
{ "data":[ { "someKey":"someValue", "anotherKey":"anotherValue" }, { "someKey":"someValue", "anotherKey":"anotherValue" } ], "paginator":{ "totalCount":12, "totalPages":6, "page":0, "size":2 } }
All successful response are sent with an HTTP response code 2xx.
Failure response format
If an API response fails, it will be sent with a non-2xx response code and JSON in the following format:
{ "timestamp":1511904038642, "code":400, "error":"Bad Request", "message":"This is why it fails" }
The HTTP status codes currently returned by the API are 301 if the API version is not supported 400 if request syntax is wrong, 401 if request is unauthorized, 404 if requesting with item ID and item is not found or request path is not supported by the API, 405 if the method is not supported, 415 if media type is not supported, 503 if request can not be served. Any internal application errors will respond with a 500 code and we will be grateful if u report them to us.
API documentation
General
Health check
Get Unimus health status.
Method: GET
http://example.unimus/api/v2/health
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/health"
Success 200
Field | Type | Description |
---|---|---|
status | String | OK - Unimus is ready to handle all requests. LICENSING_UNREACHABLE - License server is unreachable. All request will proceed except add, remove and update device. ERROR - Unimus require user interaction to solve the problem. All requests will be refused. |
HTTP/1.1 200 OK { "data":{ "status":"OK" } }
Schedules
Schedules - get schedule
Get an individual schedule.
Method: GET
http://example.unimus/api/v2/schedules/:scheduleId
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/schedules/<scheduleId>"
Parameter
Field | Type | Description |
---|---|---|
scheduleId | Number | The ID of the schedule |
Success 200
Field | Type | Description |
---|---|---|
id | Number | The ID of the schedule |
createTime | Number | Schedule creation time in seconds |
periodicity | String | Schedule periodicity. Possible values: MONTHLY, WEEKLY, DAILY, HOURLY |
dom | Number | Day of month |
dow | Number | Day of week |
hour | Number | Hour of day |
min | Number | Minute of hour |
name | String | Schedule pretty name |
HTTP/1.1 200 OK { "data":{ "id":7, "createTime":1511863250, "periodicity":"MONTHLY", "dom":1, "dow":1, "hour":0, "min":6, "name":"Every month, on day 1, at 00:06." } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 NOT FOUND { "timestamp":1511862182524, "code":404, "error":"Not Found", "message":"Schedule with id 11 not found" }
Schedules - get schedules
Get a list of all schedules in Unimus.
Method: GET
http://example.unimus/api/v2/schedules?page=:pageIndex&size=:pageSize
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/schedules?page=0&size=20"
Parameter
Name | Type | Description |
---|---|---|
pageIndex | Number | Page index (OPTIONAL) |
pageSize | Number | Page size (OPTIONAL) |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the schedule |
createTime | Number | Schedule creation time in seconds |
periodicity | String | Schedule periodicity. Possible values: MONTHLY, WEEKLY, DAILY, HOURLY |
dom | Number | Day of month |
dow | Number | Day of week |
hour | Number | Hour of day |
min | Number | Minute of hour |
name | String | Schedule pretty name |
HTTP/1.1 200 OK { "data":[ { "id":5, "createTime":1511863239, "periodicity":"MONTHLY", "dom":5, "dow":1, "hour":0, "min":0, "name":"Every month, on day 5, at 00:00." }, { "id":7, "createTime":1511863250, "periodicity":"MONTHLY", "dom":1, "dow":1, "hour":0, "min":6, "name":"Every month, on day 1, at 00:06." } ], "paginator":{ "totalCount":7, "totalPages":4, "page":1, "size":2 } }
Devices
Devices - get device by ID
Get an individual device by ID.
Method: GET
http://example.unimus/api/v2/devices/:deviceId?attr=:attributes
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices/<deviceId>?attr=s,c"
Parameter
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device |
attributes | String | Comma separated graph attribute nodes. (OPTIONAL) Possible values: device schedule: schedule, sch, s device connections: connections, conn, c |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the device |
createTime | Number | Device creation time in seconds |
address | String | Hostname, IPv4 or IPv6 |
description | String | Device description |
vendor | String | Vendor |
type | String | Type |
model | String | Model |
schedule | Object | Device schedule |
connections | Array | Device connections |
HTTP/1.1 200 OK { "data":{ "id":1, "createTime":1525101029, "address":"198.18.0.0", "description":null, "schedule":{ "id":1, "createTime":1524564606, "periodicity":"DAILY", "dom":-1, "dow":-1, "hour":3, "min":0, "name":"Every day at 03:00." }, "vendor":"MikroTik", "type":"RouterOS", "model":"Simulated-RouterOS", "connections":[ { "type":"SSH", "port":22, "credentials":[ { "id":1, "username":"test", "password":"test", "sshKey":null } ], "enablePassword":null } ] } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 400 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 400 BAD REQUEST { "timestamp":1511869830038, "code":400, "error":"Bad Request", "message":"Argument deviceId type mismatch" }
Devices - get device by address
Get an individual device by address.
Method: GET
http://example.unimus/api/v2/devices/findByAddress/:address?attr=:attributes
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices/findByAddress/<address>?page=0&size=20&attr=s,c"
Parameter
Name | Type | Description |
---|---|---|
address | String | The IPv4, IPv6 or hostname of the device |
attributes | String | Comma separated graph attribute nodes. (OPTIONAL) Possible values: device schedule: schedule, sch, s device connections: connections, conn, c |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the device |
createTime | Number | Device creation time in seconds |
address | String | Hostname, IPv4 or IPv6 |
description | String | Device description |
vendor | String | Vendor |
type | String | Type |
model | String | Model |
schedule | Object | Device schedule |
connections | Array | Device connections |
HTTP/1.1 200 OK { "data":{ "id":1, "createTime":1525101029, "address":"198.18.0.0", "description":null, "schedule":null, "vendor":"MikroTik", "type":"RouterOS", "model":"Simulated-RouterOS", "connections":[ ] } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 BAD REQUEST { "timestamp":1511862182524, "code":404, "error":"Not Found", "message":"Device with address some_address not found" }
Devices - get devices
Get a list of devices.
Method: GET
http://example.unimus/api/v2/devices?page=:pageIndex&size=:pageSize&attr=:attributes
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices?page=0&size=20&attr=s,c"
Parameter
Name | Type | Description |
---|---|---|
pageIndex | Number | Page index (OPTIONAL) |
pageSize | Number | Page size (OPTIONAL) |
attributes | String | Comma separated graph attribute nodes.(OPTIONAL) Possible values for device schedule: schedule, sch, s for device credential: credential, cred, c |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the device |
createTime | Number | Device creation time in seconds |
address | String | Hostname, IPv4 or IPv6 |
description | String | Device description |
vendor | String | Vendor |
type | String | Type |
model | String | Model |
schedule | Object | Device schedule |
connections | Array | Device connections |
HTTP/1.1 200 OK { "data":[ { "id":1, "createTime":1525101029, "address":"198.18.0.0", "description":null, "schedule":null, "vendor":"MikroTik", "type":"RouterOS", "model":"Simulated-RouterOS", "connections":[ ] } ], "paginator":{ "totalCount":1, "totalPages":1, "page":0, "size":20 } }
Devices - create new device
Create a new device.
Method: POST
http://example.unimus/api/v2/devices
curl -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d '{"address":"<address>","description":"<description>"}' "http://<example.unimus>/api/v2/devices"
Parameter
Name | Type | Description |
---|---|---|
address | String | Device address |
description | String | Description of the new device |
scheduleId | Number | Schedule id If null then device will be backed up according to system default schedule |
Success 201
Name | Type | Description |
---|---|---|
id | Number | The ID of the device |
createTime | Number | Device creation time in seconds |
address | String | Hostname, IPv4 or IPv6 |
description | String | Device description |
vendor | String | null |
type | String | null |
model | String | null |
schedule | Object | Device schedule |
connections | Array | Device connections |
HTTP/1.1 201 CREATED { "data":{ "id":1, "createTime":1525101029, "address":"198.18.0.0", "description":null, "vendor":null, "type":null, "model":null, "schedule":{ "id":1, "createTime":1524564606, "periodicity":"DAILY", "dom":-1, "dow":-1, "hour":3, "min":0, "name":"Every day at 03:00." }, "connections":[ ] } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 422 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 422 UNPROCESSABLE ENTITY { "timestamp":1511876680885, "code":422, "error":"Unprocessable Entity", "message":"Device already exist" }
Devices - update device
Update device address, description or schedule time.
Method: PATCH
http://example.unimus/api/v2/devices/:deviceId
curl -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer <token>" -X PATCH -d '{"address":"<address>","description":"<description>","scheduleId":"<scheduleId>"}' "http://<example.unimus>/api/v2/devices/<deviceId>"
Parameter
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device |
address | String | Device address |
description | String | Device description |
scheduleId | Number | Schedule id. If null then no schedule update occurs If -1 then device will be backed up according to system default schedule |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the device |
createTime | Number | Device creation time in seconds |
address | String | Hostname, IPv4 or IPv6 |
description | String | Device description |
vendor | String | Vendor |
type | String | Type |
model | String | Model |
schedule | Object | Device schedule |
connections | Array | Device connections |
HTTP/1.1 200 OK { "data":{ "id":1, "createTime":1525101029, "address":"198.18.0.0", "description":null, "schedule":{ "id":1, "createTime":1524564606, "periodicity":"DAILY", "dom":-1, "dow":-1, "hour":3, "min":0, "name":"Every day at 03:00." }, "vendor":"MikroTik", "type":"RouterOS", "model":"Simulated-RouterOS", "connections":[ ] } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 NOT FOUND { "timestamp":1511880124270, "code":404, "error":"Not Found", "message":"Device not found" }
Devices - delete device
Delete a single device from Unimus.
Method: DELETE
http://example.unimus/api/v2/devices/:deviceId
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" -X DELETE "http://<example.unimus>/api/v2/devices/<deviceId>"
Parameter
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device to delete |
Success 200
Name | Type | Description |
---|---|---|
success | String | A message stating that the deletion was successful |
HTTP/1.1 200 OK { "data":{ "success":"true" } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 NOT FOUND { "timestamp":1511884051726, "code":404, "error":"Not Found", "message":"Device with id 102 not found" }
Backups
Backups - get device backups
Get a list of all device backups. Backups are ordered descending by create time so the latest backup will always be at index 0 in the list. The list can be empty if the device has no backup yet.
Method: GET
http://example.unimus/api/v2/devices/:deviceId/backups?page=:pageIndex&size=:pageSize
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices/1/backups?page=0&size=20"
Parameter
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device |
pageIndex | Number | Page index (OPTIONAL) |
pageSize | Number | Page size (OPTIONAL) |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the backup |
validSince | Number | First time this configuration retrieved from the device |
validUntil | Number | Last time this configuration retrieved from the device. Will be null if the configuration was retrieved only once (only validSince will be set) |
type | String | Backup type. Could be TEXT or BINARY |
bytes | Array | Backup as byte array |
HTTP/1.1 200 OK { "data":[ { "id":1, "validSince":1525117527, "validUntil":null, "type":"TEXT", "bytes":"IyBTaW11bGF0ZWQgTWlrcm9UaWsgUm91dGVyT1Mgc3lzdGVtCiMgc29mdHdhcmUgaWQgPSBub25lCiMKL3NlY3Rpb24gYQpjb21tYW5kIGEKL3NlY3Rpb24gYmIKY29tbWFuZCBiYgovc2VjdGlvbiBjY2MKY29tbWFuZCBjY2MK" } ], "paginator":{ "totalCount":1, "totalPages":1, "page":0, "size":20 } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 NOT FOUND { "timestamp":1511886913012, "code":404, "error":"Not Found", "message":"Device with id 964 not found" }
Backups - get device latest backup
Get device latest backup. Backup can be null if the device has no backups yet.
Method: GET
http://example.unimus/api/v2/devices/:deviceId/backups/latest
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices/<deviceId>/backups/latest"
Parameter
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device |
Success 200
Name | Type | Description |
---|---|---|
id | Number | The ID of the backup |
validSince | Number | First time this configuration retrieved from the device |
validUntil | Number | Last time this configuration retrieved from the device. |
type | String | Backup type. Could be TEXT or BINARY |
bytes | Array | Backup as byte array |
HTTP/1.1 200 OK { "data":{ "id":1, "validSince":1525117527, "validUntil":null, "type":"TEXT", "bytes":"IyBTaW11bGF0ZWQgTWlrcm9UaWsgUm91dGVyT1Mgc3lzdGVtCiMgc29mdHdhcmUgaWQgPSBub25lCiMKL3NlY3Rpb24gYQpjb21tYW5kIGEKL3NlY3Rpb24gYmIKY29tbWFuZCBiYgovc2VjdGlvbiBjY2MKY29tbWFuZCBjY2MK" } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 404 NOT FOUND { "timestamp":1511889424942, "code":404, "error":"Not Found", "message":"Device with id 12 not found" }
Backups - get latest backups
Get a list of latest backup of devices with no particular order. Each backup is wrapped with device id and address.
Method: GET
http://example.unimus/api/v2/devices/backups/latest?page=:pageIndex&size=:pageSize&id=:deviceIds
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v2/devices/backups/latest?page=0&size=20&id=<deviceIds>"
Parameter
Name | Type | Description |
---|---|---|
pageIndex | Number | Page index (OPTIONAL) |
pageSize | Number | Page size (OPTIONAL) |
deviceIds | String | Comma separated device ids. If this parameter is not specified then backups of all devices will be returned according to pagination. |
Success 200
Name | Type | Description |
---|---|---|
deviceId | Number | The ID of the device |
address | String | Hostname, IPv4 or IPv6 |
backup | Object | Backup object |
HTTP/1.1 200 OK { "data":[ { "deviceId":1, "address":"198.18.0.0", "backup":{ "id":1, "validSince":1525117527, "validUntil":null, "type":"TEXT", "bytes":"IyBTaW11bGF0ZWQgTWlrcm9UaWsgUm91dGVyT1Mgc3lzdGVtCiMgc29mdHdhcmUgaWQgPSBub25lCiMKL3NlY3Rpb24gYQpjb21tYW5kIGEKL3NlY3Rpb24gYmIKY29tbWFuZCBiYgovc2VjdGlvbiBjY2MKY29tbWFuZCBjY2MK" } } ], "paginator":{ "totalCount":1, "totalPages":1, "page":0, "size":20 } }
Running tasks
Run job - discover device
Trigger discovery job with all devices in the system. If u want to narrow down devices included in job then specify their IDs in request parameter.
Method: PATCH
http://example.unimus/api/v2/jobs/discovery?id=:deviceIds
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" -X PATCH "http://<example.unimus>/api/v2/jobs/discovery?id=<deviceIds>"
Parameter
Name | Type | Description |
---|---|---|
deviceIds | String | Comma separated device ids to run discovery on |
Success 202
Name | Type | Description |
---|---|---|
accepted | Number | Number of started discoveries |
refused | Number | Number of refused discoveries. Discovery or backup currently running |
HTTP/1.1 202 ACCEPTED { "data":{ "accepted":12, "refused":0 } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 403 NOT FOUND { "timestamp":1511897481896, "code":404, "error":"Not Found", "message":"Devices not found [3]" }
Run job - discover un-discovered devices
Trigger discovery job for all undiscovered devices.
Method: PATCH
http://example.unimus/api/v2/jobs/discovery/undiscovered
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" -X PATCH "http://<example.unimus>/api/v2/jobs/discovery/undiscovered"
Success 202
Name | Type | Description |
---|---|---|
accepted | Number | Number of started discoveries |
refused | Number | Number of refused discoveries. Discovery or backup currently running |
HTTP/1.1 202 ACCEPTED { "data":{ "accepted":12, "refused":0 } }
Run job - backup device
Trigger backup job with all devices in the system. If u want to narrow down devices included in job then specify their IDs in request parameter.
Method: PATCH
http://example.unimus/api/v2/jobs/backup?id=:deviceIds
curl -H "Accept: application/json" -H "Authorization: Bearer <token>" -X PATCH "http://<example.unimus>/api/v2/jobs/backup?id=<deviceIds>"
Parameter
Name | Type | Description |
---|---|---|
deviceIds | String | Comma separated device ids to run backup on |
Success 202
Name | Type | Description |
---|---|---|
accepted | Number | Number of started backups |
refused | Number | Number of refused backups |
sentForDiscovery | Number | Un-discovered devices sent for discovery |
HTTP/1.1 202 ACCEPTED { "data":{ "accepted":0, "refused":2, "sentForDiscovery":0 } }
Error 4xx
Name | Type | Description |
---|---|---|
timestamp | Number | Current timestamp |
code | Number | 404 |
error | String | HTTP code message |
message | String | Error message |
HTTP/1.1 403 NOT FOUND { "timestamp":1511899365179, "code":404, "error":"Not Found", "message":"Devices not found [16, 23, 15]" }