API Methods for version 1.2.0 and later : Network Systems

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&flows_type=app&start=1422867540&end=1422953640&router=pe1-cpt1.irisns.net&OUT_IFNAME=Gi0/3.20

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&start=1422867540&end=1422953640&flows_type=custom&select=app&select=srcaddr

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&start=1422867540&end=1422953640&flows_type=app

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21,10.12.76.11&start=1422867540&end=1422953640&flows_type=app&IPV4_SRC_ADDR=192.168.10.0/24,192.168.11/24

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21,10.12.76.11&start=1422867540&end=1422953640&flows_type=app&IPV4_SRC_ADDR=192.168.10.0/24,!192.168.10.5

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&start=1422867540&end=1422953640&flows_type=custom&IPV4_SRC_ADDR=192.168.10.0/24,!192.168.10.5

Get totals for http and https only:

curl -u api_user:api_passwd -H "Accept: application/json" -H "Content-type: application/json" -X GET \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&start=1422867540&end=1422953640&flows_type=custom&APPLICATION=80,443

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 \

http://your-dce-server/iris/api2/api/flows?limit=100&flowengine=10.12.76.21&start=1422867540&end=1422953640&flows_type=custom&APPLICATION=80,443&IPV4_SRC_ADDR=172.16.0.0/24&select=dstaddr

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

http://your-dce-server/iris/api2/api/graphs?search.view_code=ABC-123&search.graphtype=snipsAvailability&search.basetag.not_like=%25\_\_%25

To return only interfaces

http://your-dce-server/iris/api2/api/graphs?search.view_code=ABC-123&search.graphtype=ifavailability&search.basetag.like=%25\_\_%25

To get all PRIMARY and FAILOVER interface (basetag contains "__") graphs of type "ifavailability" for view code “ABC-123”

http://your-dce-server/iris/api2/api/graphs?search.view_code=ABC-123&search.graphtype=ifavailability&search.basetag.like=%\_\_%&search.mnemonic.like=%25PRIMARY%25&search.mnemonic.like=%25FAILOVER%25

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

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

http://your-dce-server/iris/api2/api/graphs?search.view_code=ABC-123&search.graphtype=ifavailability&search.mnemonic.like=%25PRIMARY%25&search.mnemonic.like=%25FAILOVER%25

Alternatively, you can pass an encode_json as a search=parameter: http://your-dce-server/iris/api2/api/graphs?search='JSON(PAYLOAD)'

Retrieve graph data for specific intervals specified via the ‘step’ parameter. http://my-iris-server/iris/api2/api/graphs/xport?gdef=iftraffic&basetag=Core-Bree%20Traffic%20%28st%29&starttime=1522845522&endtime=1522852722&step=300

Network Systems

How can we help you today?

API Methods for version 1.2.0 and later Print

How can we help you today?

API Methods for version 1.2.0 and later Print

Related Articles