Data Operations
To draw a graph in Iris is a 2 step process. First you need to find the graph and then get the data either as an image or text.
GET graphs
You can use this method to find graphid's and graphtypes so that you can draw graph and get data.
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/graphs?search.graphtype=iftraffic&search.view_code=ABC001
You can filter the output by adding the optional parameters "search.mnemonic" to search the description line, "search.view_code" or "search.graphtype". If you don't specify, all graphs will be returned. The output looks something like this:
[
{
"graphdescr" : "Interface Traffic",
"gdef" : "iftraffic",
"createdhow" : "A",
"lastupdate" : "1369061989",
"rrdname" : "cr1.cpt1.za__xe-0%2F1%2F0.0.netIf.rrd",
"rrdtype" : "netIf",
"rrdpath" : "juniperRouter/fb/cr1.cpt1.za__xe-0%2F1%2F0.0.netIf.rrd",
"tier3" : null,
"tier2" : null,
"bhspec" : "8-24,0-24,0-24",
"timezone" : null,
"boring" : 0,
"instance" : "juniperRouter",
"archived" : 0,
"views_id" : "1047",
"view_code" : "VOX110",
"device" : "cr1.cpt1.za",
"tier1" : "xe-0/1/0.0",
"graphs_id" : "2831273",
"hidden" : 0,
"graphtype" : "iftraffic",
"alias" : null,
"rank" : "81631005",
"mnemonic" : "cr1.cpt1.za__xe-0/1/0.0",
"basetag" : "cr1.cpt1.za__xe-0/1/0.0"
}
]
GET graphs/data
The method takes option start and end times as parameters as shown below. If not specified the default of 24 hours is assumed. You need to provide either the graphid as parameter, or the basetag and graphtype parameters.
As an image (here you'll need to wrap the calling URL inside an <image> tag in your html)...
curl -u api_user:api_passwd -H "Accept: image/png" -H "Content-type: image/png" -X GET \
http://your-dce-server/iris/api2/api/graphs/data?id=310054&endtime=1369140507&starttime=1366548507
...using basetag and graphtype...
curl -u api_user:api_passwd -H "Accept: image/png" -H "Content-type: image/png" -X GET \
http://your-dce-server/iris/api2/api/graphs/data?basetag=pe1__Ge1%2F0.204&graphtype=iftraffic
In 1.2.1+ however, you will need to replace the “data” with “image”, as seen in the following examples:
curl -u api_user:api_passwd -H "Accept: image/png" -H "Content-type: image/png" -X GET \
http://your-dce-server/iris/api2/api/graphs/image?id=310054&endtime=1369140507&starttime=1366548507
curl -u api_user:api_passwd -H "Accept: image/png" -H "Content-type: image/png" -X GET \
http://your-dce-server/iris/api2/api/graphs/image?basetag=pe1__Ge1%2F0.204&graphtype=iftraffic
...or as text...
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/graphs/data?id=310054&endtime=1369140507&starttime=1366548507
{
"Avg % In" : {
"value" : "5.62%",
"value_unformat" : "5.62"
},
...
"Max % Out" : {
"value" : "11.87%",
"value_unformat" : "11.87"
}
}
The following parameters can be set for images:
&view=small
&vlegend=somelegend
&width=400
&height=120
&nolegend=1
&title=my%20graph%20title
'''Note: if you are using the ID to lookup the graphs, you should perform a search to lookup the ID each time.''' There is no guarantee that the ID will remain the same as data changes. If it is a real concern use the basetag / graphtype method to get the data.
Netflow Data Operations
GET flow data
Flow queries are constructed by combining input and output columns in your query (quite similar to SQL for relational databases, except that it's not a database). A typical example would be:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
It will return something similar to this:
<pre>
{
success: true,
totalcount: "200",
data: [
{
direction: "out",
perc: "0.215003620110549",
bytes: 16695381562,
app: "http",
packets: "26137278",
prot: "tcp",
wildcard: "*"
},
{
direction: "out",
perc: "0.142294610184124",
bytes: 11049408424,
app: "https",
packets: "23550550",
prot: "tcp",
wildcard: "*"
}
...
</pre>
Input arguments
The following are mandatory arguments:
- start=<epoch timestamp>
- end=<epoch timestamp>
These are optional arguments:
- flows_type=<type> (See flow types below)
- limit=<max records to return (default is 100)
- flowengine=<flowengine name or ip> (You can specify multiple args or separate with comma)
These are input arguments (like the WHERE clause in SQL):
- router (device name or IP address)
- APPLICATION (based on UDP/TCP ports)
- AS_PATH_1
- AS_PATH_2
- AS_PATH_3
- AS_PATH_4
- AS_PATH_5
- DST_AS
- DST_COUNTRY (based on GeoIP lookup)
- DST_TOS
- EXADDR (the device IP addess)
- FIRST_SWITCHED (epoch timestamp)
- INPUT_SNMP (snmp ifIndex of input interface)
- IN_BYTES (read this as just "bytes" legacy used OUT_BYTES, but we only use the one column now)
- IN_IFNAME (the snmp ifName of the input interface)
- IN_PKTS (read as just "packets" as per IN_BYTES)
- IPV4_DST_ADDR
- IPV4_DST_MASK
- IPV4_NEXTHOP
- IPV4_SRC_ADDR
- IPV4_SRC_MASK
- L4_DST_PORT
- L4_SRC_PORT
- LAST_SWITCHED (epoch timestamp)
- OUTPUT_SNMP
- OUT_BYTES (deprecated)
- OUT_IFNAME ( the snmp ifName of the ouptut interface)
- OUT_PKTS (deprecated)
- PROTOCOL
- SRC_AS
- SRC_COUNTRY (based on GeoIP lookup)
- SRC_TOS
Note: The following columns can only be used if the device exporting netflow has been discovered in Iris:
- router
- IN_IFNAME
- OUT_IFNAME
Output arguments
Output is controlled via the flows_type= argument. You can choose to select exactly which columns you want by specifying arguments like:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
The following is a complete list of all columns. You will ALWAYS get "bytes" and "packets", no need to specify these:
- bytes
- packets
- srcaddr
- dstaddr
- srcport
- dstport
- srcas
- dstas
- prot
- tos
- srctos
- dsttos
- srccountry
- dstcountry
- app
- device
- ifin
- ifout
You can select any of the following pre-defined templates by specifying in the flows_type argument. eg:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
- asn
- country
- srcaddr
- dstaddr
- app
- ip
- protocol
- device
More GET flows examples
Get application flows for 2 source ip ranges from multiple flow engines:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
Get application flows for source ip range with exclusion:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
Get totals only for specific ip range with exclusion:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
Get totals for http and https only:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
Get dest ip's for source range for only http and https traffic:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
View (Customers / Groups / Views) Operations
GET view
To get a list of all views:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/views
To retrieve a view with code 'CUST-123':
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/views/CUST-123
To get a list of all customers:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/views?search.type=CUSTOMER
The valid types are:
- AREA
- CAMPUS
- COUNTRY
- CUSTOMER
- DEVICEGROUP
- DIVISION
- GROUP
- INSTITUTION
- LABEL
- METRO_RING
- MNEMONIC_GROUP
- NETWORK
- NODE
- RING
- SERVICE_GROUP
- SITE
- STACK
POST/PUT views
To create a new view:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"name": "Customer ABC",
"code": "ABC-123",
"viewprofiles_id": "1",
"descr": "Some descr",
"timezone": "Africa/Johannesburg",
"bh_start_week": "8",
"bh_end_week": "17",
"bh_start_sat": "9",
"bh_end_sat": "17",
"bh_start_sun": "9",
"bh_end_sun": "13",
"allow_netflow": "true",
"views_views_children":[{"parent":{"code":"Parent_ABC"}}]
}'
http://your-dce-server/iris/api2/api/views
The above call creates a view with a parent view (with code Parent_ABC) assigned. To create a view with a child view assigned, it will have:
"views_views_parents":"[{"child":["code":"Child_ABC"}}]
To update a view:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"name": "ABC Network",
"allow_netflow": "false"
}'
http://your-dce-server/iris/api2/api/views/ABC-123
DELETE views
curl -u api_user:api_passwd -X DELETE http://your-dce-server/iris/api2/api/views/ABC-123
User Operations
GET users
To get a list of all users:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/users
To retrieve a user with username 'joe':
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/users/joe
POST/PUT users
To create a new user:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"username":"joe"
"passwd":"123456",
"name":"Joe Soap",
"email":"joe@suds.co.za",
}'
http://your-dce-server/iris/api2/api/users
To update a new user:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"passwd":"234567",
}'
http://your-dce-server/iris/api2/api/users/joe
DELETE users
curl -u api_user:api_passwd -X DELETE http://your-dce-server/iris/api2/api/users/joe
Mnemonic Operations
GET mnemonics
To get a list of all mnemonics:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/mnemonics
To find a mnemonic by mnemonics_id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/mnemonics/mnemonics_id
POST/PUT mnemonics
Mnemonics are updated in one of two ways. You either get the mnemonics_id (which you'll get using GET above, or you have use the basetag. The basetag is constructed from the router hostname + interface ifName. For example "mi-za-pe1" + "Se0/1" = ''mi-za-pe1__Se0/1". Using the basetag is probably the easiest way as you don't need to make 2 calls.
The below is updating using the mnemonics_id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"alias": "Link to Benoni",
"circuit_ident": "64-12345-00",
"notes": "Call toll-free 0800 123 321",
"serviceimpact": "MINOR",
"servicetag": "Diginet Link (primary)"
"vrf": "abc-vrf-1"
}'
http://your-dce-server/iris/api2/api/mnemonics/1846
To update all mnemonics with basetag 'mi-za-pe1__Se0/0':
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"search": {"basetag":"mi-za-pe1__Se0/1"},
"servicetag": "Diginet Link (primary)"
"vrf": "abc-vrf-1"
}' \
http://your-dce-server/iris/api2/api/mnemonics
You could also use this method to update all mnemonics where the mnemonic field matching something specific.
Device Operations
GET devices
To get a list of all devices:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/devices
To find a device by id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/devices/1234
POST/PUT devices
To create a new device:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{"hostname":"api_device","multi_tenant":"1","monitoring":"DEVICE","poller_a":"838","type":"CISCO_ROUTER","object":"device","deviceprofiles_id":"26","snmp_version":"2c","ipaddress":"10.0.0.1","devices_views":[{"view":{"code":"CUST-123"}}]}' \
http://your-dce-server/iris/api2/api/devices
DELETE devices
There are two ways to delete a device:
This shows how to mark the device as deleted giving you the ability to undelete the device on the frontend:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"deleted":true}'
http://your-dce-server/iris/api2/api/devices/device_id
The following deletes the device from the system (this can not be undone):
curl -u api_user:api_passwd -X DELETE http://your-dce-server/iris/api2/api/devices/device_id
Using poller/profile names instead of ID:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{"hostname":"api_device","multi_tenant":"1","monitoring":"DEVICE","poller_a_rel"{"hostname”:”poller.co.za"},"type":"CISCO_ROUTER","object":"device","deviceprofile":{"profilename":"CISCO_ROUTER"},"snmp_version":"2c","ipaddress":"10.0.0.1"}' \
http://your-dce-server/iris/api2/api/devices
Threshold Operations
GET thresholds
To get a list of all thresholds:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/thresholds
To find a threshold by id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/thresholds/95
POST/PUT thresholds
To create a new threshold:
curl -u api_user:api_test -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"descr":"api-threshold",
"gdef":"ifavailability",
"var":"down",
"period":"-15min",
"crit_ceiling":"50",
"crit_ceiling_msg":"%k breached max value of %t (%v)",
"mnemonic_pattern":"em1",
"views_id":"431",
"impact_service":"4",
"weight":"100",
"exception":"false"
}' http://your-dce-server/iris/api2/api/thresholds
DELETE thresholds
Deleting a threshold with the option to undelete from the frontend:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \ -d '{"deleted":true}'
http://your-dce-server/iris/api2/api/thresholds/95
Notification Group Operations
GET notification groups
To get a list of all notification groups:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/notifygroups
To find a notification group by id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/notifygroups/95
POST/PUT notification groups
To create a new notification group:
curl -u apiuser:apitest -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"groupname":"api_group",
"notifyhoursstart":"8",
"notifyhoursend":"22",
"views_id":"431",
"emaillist":"api@nowhere.com",
"phonelist":"0824424325"
}' http://your-dce-server/iris/api2/api/notifygroups
DELETE notification groups
Deleting a notification group with the option to undelete from the frontend:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \ -d '{"deleted":true}'
http://your-dce-server/iris/api2/api/notifygroups/213
Alarm Notification Operations
GET alarm notifications
To get a list of all alarm notifications:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/notifyalarms
To find an alarm notification by id:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \
http://your-dce-server/iris/api2/api/notifyalarms/79
POST/PUT alarm notifications
To create a new alarm notification:
curl -u apiuser:apitest -H "Accept: application/json" -H "Content-type: application/json" -X POST \
-d'{
"source":"THRESMON",
"severity":"2",
"match_views_id":"431",
"regex_descrkey":"api-threshold",
"regex":"em1",
"regex_device":"twelves",
"notifygroups_id":"506"
}' http://your-dce-server/iris/api2/api/notifyalarms
DELETE alarm notification
Deleting an alarm notification with the option to undelete from the frontend:
curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X POST \ -d '{"deleted":true}'
http://your-dce-server/iris/api2/api/notifyalarms/79
More Operations
Here are some examples of advance commands that can be used in the API:
To return only devices
To return only interfaces
To get all PRIMARY and FAILOVER interface (basetag contains "__") graphs of type "ifavailability" for view code “ABC-123”
To verify that the view with code "ABC-123” exists
http://your-dce-server/iris/api2/api/graphs?search.view_code=ABC-123
Check to see if there is a graph
http://your-dce-server/iris/api2/api/graphs?search.basetag=LAB-SW-01_Gi0/17
Or
http://your-dce-server/iris/api2/api/graphs/data?basetag=LAB-SW-01_Gi0/17&graphtype=iftraffic
To search for graphs that have a specific mnemonic string
Alternatively, you can pass an encode_json as a search=parameter: http://your-dce-server/iris/api2/api/graphs?search='JSON(PAYLOAD)'