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


 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

 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)'