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.

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": {

"some key": "some value",

"another key": "another value"

}

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": [

{

"some key": "some value",

"another key": "another value"

},

{

"some key": "some value",

"another key": "another value"

}

],

"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 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/v1/heatlh

CURL

curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v1/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/v1/schedules/:scheduleId

CURL

curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v1/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/v1/schedules?page=:pageIndex&size=:pageSize

CURL

curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v1/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

Get an individual device.

Method: GET

http://example.unimus/api/v1/devices/:deviceId?attr=:attributes

CURL

curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimuis>/api/v1/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 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
port	Number	Device port
connector	String	Connector type, possible values: SSH, TELNET
vendor	String	Vendor
type	String	Type
model	String	Model
schedule	Object	Device schedule
credential	Object	Credential used to login to the device

HTTP/1.1 200 OK

{

"data": {

"id": 1,

"createTime": 1511339013,

"address": "198.18.0.29",

"description": "Back bone device",

"port": 22,

"connector": "SSH",

"vendor": "MikroTik",

"type": "RouterOS",

"model": "Simulated-RouterOS",

"schedule": null,

"credential": {

"id": 1,

"username": "test",

"password": "test",

"sshKey": 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 devices

Get a list of devices.

Method: GET

http://example.unimus/api/v1/devices?page=:pageIndex&size=:pageSize&attr=:attributes

CURL

curl -H "Accept: application/json" -H "Authorization: Bearer <token>" "http://<example.unimus>/api/v1/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
port	Number	Device port
connector	String	Connector type, possible values: SSH, TELNET
vendor	String	Vendor
type	String	Type
model	String	Model
schedule	Object	Device schedule
credential	Object	Credential used to login to the device

HTTP/1.1 200 OK

{

"data": [

{

"id": 2,

"createTime": 1511339013,

"address": "198.18.0.2777",

"description": null,

"port": 22,

"connector": null,

"credential": null,

"vendor": "MikroTik",

"type": "RouterOS",

"model": "Simulated-RouterOS",

"schedule": {

"id": 1,

"createTime": 1511339012,

"periodicity": "DAILY",

"dom": 1,

"dow": 1,

"hour": 3,

"min": 0,

"name": "Every day at 03:00."

}

],

"paginator": {

"totalCount": 29,

"totalPages": 29,

"page": 1,

"size": 1

}