API Integration Example: SevOne

REST API Overview #

This document provides various examples of connecting to a SevOne REST API from edgeSuite. It is written against SevOne version 5.6.

Please see the following link as needed for SevOne REST API documentation and explorer:
https://<SevOne Instance>/api/docs/index.html#/

REST API Authentication #

Access to the SevOne REST API requires a token that is obtained via a request to:

URL: https://<SevOne Instance>/api/v1/authentication/signin
name:                    <user name>
password:              <password>

The authentication token is returned as follows:

<authentication>
<token>b1e9484f72406ecf724011e67240a7da7240d4ae5280ef5f</token>
</authentication>

The following cURL reference illustrates the authentication token request:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"name\": \"<user name>\",
  \"password\": \"password\"
}" "https://<SevOne Instance>/api/v1/authentication/signin"

The authentication token is then embedded in the header for subsequent requests by edgeSuite. cURL reference example below:

curl -X GET --header "Accept: application/json" --header "X-AUTH-TOKEN: b1e9484f72406ecf724011e67240a7da7240d4ae5280ef5f" 
"https://<SevOne Instance>/api/v1/alerts?size=20"

Configuring edgeSuite SSO for SevOne Rest API #

edgeSuite SSO handles acquisition of the authentication token and uses it for subsequent requests to the SevOne REST API.  To enable the REST API SSO, copy the SevOneRESTSso.js file to the edgeSuite <Install_Home>/webrules/generic/sso/ directory. When creating a connection to SevOne, set the SSO Handler to SevOneRESTSso. 

REST API Example Connection Configuration #

edgeSuite connects to the SevOne REST API using a Web Data Connection. An example Connection Configuration for the SevOne REST API is presented below:

Connection Property Example
Connection Name SevOne REST API
Destination https://<SevOneRestApiEndpoint>
SSO Handler SevOneRESTSso
SSO Credentials Username: <sevone user>
Password: <sevone password>

Example Feed Configurations #

edgeSuite makes requests to the SevOne REST API using the JSON Feed.  Below are defaults for all SevOne Feed configuration properties, unless otherwise specified:

Default Feed Property Value
Request Headers None
Rule Name BaseData
Logging Production
Poll Period 60
Enable Server Subscription Yes

Listed below are a series of sample JSON Feed Configurations that make requests to the SevOne REST API:

SevOne Get Active Incidents #
Feed Property Value
Feed Name SevOne Get Alerts
Start URI /api/v1/alerts?size=5000
HTTP Method GET
JSON Path $.content
SevOne Get Device Groups #
Feed Property Value
Feed Name SevOne Get Device Groups
Start URI /api/v1/devicegroups?size=1000&includeMembers=false
HTTP Method GET
JSON Path $.content
SevOne Get Devices #
Feed Property Value
Feed Name SevOne Get Devices
Start URI /api/v1/devices?size=10000
HTTP Method GET
JSON Path $.content
SevOne Get Object Groups #
Feed Property Value
Feed Property Value
Feed Name SevOne Get Object Groups
Start URI /api/v1/objectgroups?size=1000&includeMembers=false
HTTP Method GET
JSON Path $.content
SevOne Get Alerts by Device #
Feed Property Value
Feed Name SevOne Get Alerts by Device
Start URI /api/v1/alerts/devices/{nodeVar.SevOneDeviceID}?Alert%20status=open&size=1000
HTTP Method GET
JSON Path $.alerts
SevOne Get Objects by Device #
Feed Property Value
Feed Name SevOne Get Objects by Device
Start URI /api/v1/devices/{nodeVar.SevOneDeviceID}/objects?size=20&includeIndicators=false
HTTP Method GET
JSON Path $.[*][*]