QUESTION
How to access the Traverse REST API?
RESOLUTION
The REST API allows access to many of Traverse's features and is documented in the Traverse Developer Guide.
In order to establish a session with the REST API, a login request must be sent with valid Traverse username and password using a REST client or Web Browser:
https://10.10.10.10/api/rest/command/login?superuser/traverse
OK 201 request accepted and processed, ready for next request
The response from the REST API will contain authentication credentials in the form of a cookie with the key 'TraverseJSessionID'. This cookie may then be included in the header of subsequent requests.
Note that most Web Browsers will automatically cache the cookie provided in the 'login' response, and include it in subsequent requests. When using a REST client it may be necessary to explicitly capture the cookie and use it in subsequent requests.
Once an authenticated session has been established, we may then issue any of the REST API commands (which are similar to BVE API commands), such as:
https://10.10.10.10/api/rest/command/test.list?deviceName=Traverse Server&testType=jmx&subType=nv_msgsvr_event_reject
With a response of:
OK 203 request accepted, records returned: 3 "serialNumber=90040", "testName=Number Of Messages Discarded (By Rule)", "testType=jmx", "subType=nv_msgsvr_event_reject", "deviceName=Traverse Server", "accountName=Core Infrastructure", "jmxremotePort=7693", "protocol=IIOP", "remoteApplicationDomainName=", "loginName=", "interval=300", "warningThreshold=5000", "criticalThreshold=20000", "shadowWarningThreshold=5000", "shadowCriticalThreshold=20000", "slaThreshold=5000", "units=msgs/min", "actionName=None", "scheduleName=Default Schedule", "flapPreventionWaitCycles=0", "thresholdType=1", "suppressed=false", "isSuspended=false", "timeBasedThresholds=false", "resultProcessDirective=3", "resultMultiplier=60.0", "maxValue=100000","jmxProperty=NetVigil:type=MessageServer|MessagesDiscardedByRule" "serialNumber=90029", "testName=Number Of Messages Discarded (No Match)", "testType=jmx", "subType=nv_msgsvr_event_reject", "deviceName=Traverse Server", "accountName=Core Infrastructure", "jmxremotePort=7693", "protocol=IIOP", "remoteApplicationDomainName=", "loginName=", "interval=300", "warningThreshold=5000", "criticalThreshold=20000", "shadowWarningThreshold=5000", "shadowCriticalThreshold=20000", "slaThreshold=5000", "units=msgs/min", "actionName=None", "scheduleName=Default Schedule", "flapPreventionWaitCycles=0", "thresholdType=1", "suppressed=false", "isSuspended=false", "timeBasedThresholds=false", "resultProcessDirective=3", "resultMultiplier=60.0", "maxValue=100000","jmxProperty=NetVigil:type=MessageServer|MessagesDiscardedNoMatchingRule" "serialNumber=90020", "testName=Number Of Messages Discarded (Unknown Device)", "testType=jmx", "subType=nv_msgsvr_event_reject", "deviceName=Traverse Server", "accountName=Core Infrastructure", "jmxremotePort=7693", "protocol=IIOP", "remoteApplicationDomainName=", "loginName=", "interval=300", "warningThreshold=5000", "criticalThreshold=20000", "shadowWarningThreshold=5000", "shadowCriticalThreshold=20000", "slaThreshold=5000", "units=msgs/min", "actionName=None", "scheduleName=Default Schedule", "flapPreventionWaitCycles=0", "thresholdType=1", "suppressed=false", "isSuspended=false", "timeBasedThresholds=false", "resultProcessDirective=3", "resultMultiplier=60.0", "maxValue=100000","jmxProperty=NetVigil:type=MessageServer|MessagesDiscardedNoMatchingDevice"
Output may also be presented in JSON format by including the 'format=json' parameter in the request:
https://10.10.10.10/api/rest/command/device.list?deviceName=Traverse Server&format=json
with a response of:
{"api-response":{"data":{"object":[{"serialNumber":"80018","deviceName":"Traverse Server","address":"127.0.0.1","deviceType":"Linux/Other Unix","parentNames":"","tag1 (Tag 1)":"","tag2 (Tag 2)":"","tag3 (Tag 3)":"","tag4 (Tag 4)":"","tag5 (Tag 5)":"","locationName":"Corporate","dgeName":"dge-1","isSuspended":"false","clearOnOk":"false","smartNotify":"true","showOnSummary":"true","accountSerialNumber":"49","accountName":"Core Infrastructure","isReadOnly":"false","model":"2.6.32-573.7.1.el6.x86_64","vendor":"Linux","rediscoveryEnabled":"false","configBackupEnabled":"false","processCollectionEnabled":"true","flapPreventionWaitCycles":"-1","comment":"Performance of Kaseya Traverse running on the local server"}]},"status":{"code":"203","error":"false","message":"request accepted, records returned: 1"}}}
Using a utility such as 'http://jsonviewer.stack.hu/' to format the output shows:
{
"api-response": {
"data": {
"object": [
{
"serialNumber": "80018",
"deviceName": "Traverse Server",
"address": "127.0.0.1",
"deviceType": "Linux/Other Unix",
"parentNames": "",
"tag1 (Tag 1)": "",
"tag2 (Tag 2)": "",
"tag3 (Tag 3)": "",
"tag4 (Tag 4)": "",
"tag5 (Tag 5)": "",
"locationName": "Corporate",
"dgeName": "dge-1",
"isSuspended": "false",
"clearOnOk": "false",
"smartNotify": "true",
"showOnSummary": "true",
"accountSerialNumber": "49",
"accountName": "Core Infrastructure",
"isReadOnly": "false",
"model": "2.6.32-573.7.1.el6.x86_64",
"vendor": "Linux",
"rediscoveryEnabled": "false",
"configBackupEnabled": "false",
"processCollectionEnabled": "true",
"flapPreventionWaitCycles": "-1",
"comment": "Performance of Kaseya Traverse running on the local server"
}
]
},
"status": {
"code": "203",
"error": "false",
"message": "request accepted, records returned: 1"
}
}
}
Here is an example using 'curl' to send a request using the authenticated session cookie provided by the 'login' service:
curl -k -X GET https://10.10.10.10/api/rest/command/device.list \
-H 'Cache-Control: no-cache' \
-H 'accept: */*' \
-H 'cookie: TraverseJSessionID=67F2BC7A6717F21379F618A07CBCAF9A'
Command to create JMX Time since results.
https://xx.xx.xx.xx/api/rest/command/test.create?devicename=Traverse%20Server&testType=jmx&subtype=nv_dge_collector_timestamp&testName=Time%20Since%20Result%20From DGE%20Extension%20(dge-ext-name)&jmxProperty=NetVigil%3Aname%3DDataCollector%2Cid%3Ddge-ext-3%7CTimeSinceLastResult&warningThreshold=900&criticalThreshold=3600&units=&resultMultiplier=1&resultProcessDirective=8&maxValue=0&jmxremotePort=7692
Where
xx.xx.xx.xx BVE IP
devicename= Your Traverse Server Name
testName=Time%20Since%20Result%20From DGE%20Extension%20(dge-ext-name) --> Replace the dge-ext-name according to your DGEx name
jmxProperty=NetVigil%3Aname%3DDataCollector%2Cid%3Ddge-ext-name%7CTimeSinceLastResult --> Replace the dge-ext-name according to your DGEx name
Lastly, the 'logout' command may be used to terminate the session:
https://10.10.10.10/api/rest/command/logout?superuser/traverse
Note: We strongly recommend 'HTTPS' (SSL) to encrypt the communication with the Traverse REST API. With HTTP all information is sent in clear text including the username, password and basic authentication credentials.
Please review the Traverse Developer Guide for additional details on the various Traverse APIs.
REFERENCE