diff --git a/html/api_v1.php b/html/api_v1.php index 642465ab3..34ec25613 100644 --- a/html/api_v1.php +++ b/html/api_v1.php @@ -24,36 +24,18 @@ include_once("../includes/rrdtool.inc.php"); require 'includes/Slim/Slim.php'; \Slim\Slim::registerAutoloader(); $app = new \Slim\Slim(); -require_once("../includes/api_functions.inc.php"); +require_once("includes/api_functions.inc.php"); $app->setName('api'); $app->group('/api', function() use ($app) { $app->group('/v1', function() use ($app) { - $app->group('/get', function() use ($app) { - $app->group('/graph', function() use ($app) { - $app->group('/port', function() use ($app) { - $app->get('/id/:id(/:type)(/:width)(/:height)(/:from)(/:to)(/)', 'authToken', 'get_graph_by_id');//api/v1/get/graph/port/id/$port_id - $app->get('/device/:id/:port(/:type)(/:width)(/:height)(/:from)(/:to)(/)', 'authToken', 'get_graph_by_port');//api/v1/get/graph/port/device/$device_id/$ifName - $app->get('/hostname/:hostname/:port(/:type)(/:width)(/:height)(/:from)(/:to)(/)', 'authToken', 'get_graph_by_port_hostname');//api/v1/get/graph/port/device/$hostname/$ifName - }); - $app->group('/general', function() use ($app) { - $app->get('/device/:id/:type(/:width)(/:height)(/:from)(/:to)(/)', 'authToken', 'get_graph_generic_by_deviceid');//api/v1/get/graph/general/device/$device_id/$graph_type - $app->get('/hostname/:hostname/:type(/:width)(/:height)(/:from)(/:to)(/)', 'authToken', 'get_graph_generic_by_hostname');//api/v1/get/graph/general/hostname/$hostname/$graph_type - }); - }); - $app->group('/stats', function() use ($app) { - $app->group('/port', function() use ($app) { - $app->get('/id/:id(/)', 'authToken', 'get_port_stats_by_id');//api/v1/get/stats/port/id/$port_id - $app->get('/device/:id/:port(/)', 'authToken', 'get_port_stats_by_port');//api/v1/get/stats/port/device/$device_id/$ifName - }); - }); - }); - $app->group('/list', function() use ($app) { - $app->get('/devices(/:order)(/:type)(/)', 'authToken', 'list_devices');//api/v1/list/devices (order can be any device column) (types = all, ignored, up, down, disabled) - }); - $app->group('/add', function() use ($app) { - $app->post('/device(/)', 'authToken', 'add_device');//api/v1/add/device (json data needs to be passed) + $app->group('/devices', function() use ($app) { + $app->get('/:hostname/ports/:ifname/:type', 'authToken', 'get_graph_by_port_hostname');//api/v1/devices/$hostname/ports/$ifName/$type + $app->get('/:hostname/:type', 'authToken', 'get_graph_generic_by_hostname');//api/v1/devices/$hostname/$type + $app->get('/:hostname/ports/:ifname', 'authToken', 'get_port_stats_by_port_hostname');//api/v1/devices/$hostname/ports/$ifName }); + $app->get('/devices', 'authToken', 'list_devices');//api/v1/devices + $app->post('/devices', 'authToken', 'add_device');//api/v1/devices (json data needs to be passed) }); }); diff --git a/includes/api_functions.inc.php b/html/includes/api_functions.inc.php similarity index 72% rename from includes/api_functions.inc.php rename to html/includes/api_functions.inc.php index 3e0695a3c..0e42a25cb 100644 --- a/includes/api_functions.inc.php +++ b/html/includes/api_functions.inc.php @@ -183,56 +183,6 @@ function authToken(\Slim\Route $route) } } -function get_graph_by_id() -{ - // This will return a graph for a given port by the port id - global $config; - $app = \Slim\Slim::getInstance(); - $router = $app->router()->getCurrentRoute()->getParams(); - $vars = array(); - $vars['id'] = $router['id']; - $vars['type'] = $router['type'] ?: 'port_bits'; - if(!empty($router['from'])) - { - $vars['from'] = $router['from']; - } - if(!empty($router['to'])) - { - $vars['to'] = $router['to']; - } - $vars['width'] = $router['width'] ?: 1075; - $vars['height'] = $router['height'] ?: 300; - $auth = "1"; - $app->response->headers->set('Content-Type', 'image/png'); - require("includes/graphs/graph.inc.php"); -} - -function get_graph_by_port() -{ - // This will return a graph for a given port by the ifName - global $config; - $app = \Slim\Slim::getInstance(); - $router = $app->router()->getCurrentRoute()->getParams(); - $device_id = $router['id']; - $vars = array(); - $vars['port'] = urldecode($router['port']); - $vars['type'] = $router['type'] ?: 'port_bits'; - if(!empty($router['from'])) - { - $vars['from'] = $router['from']; - } - if(!empty($router['to'])) - { - $vars['to'] = $router['to']; - } - $vars['width'] = $router['width'] ?: 1075; - $vars['height'] = $router['height'] ?: 300; - $auth = "1"; - $vars['id'] = dbFetchCell("SELECT `P`.`port_id` FROM `ports` AS `P` WHERE `P`.`device_id`=? AND `P`.`ifName`=?", array($device_id,$vars['port'])); - $app->response->headers->set('Content-Type', 'image/png'); - require("includes/graphs/graph.inc.php"); -} - function get_graph_by_port_hostname() { // This will return a graph for a given port by the ifName @@ -241,75 +191,37 @@ function get_graph_by_port_hostname() $router = $app->router()->getCurrentRoute()->getParams(); $hostname = $router['hostname']; $vars = array(); - $vars['port'] = $router['port']; + $vars['port'] = $router['ifname']; $vars['type'] = $router['type'] ?: 'port_bits'; - if(!empty($router['from'])) + if(!empty($_GET['from'])) { - $vars['from'] = $router['from']; + $vars['from'] = $_GET['from']; } - if(!empty($router['to'])) + if(!empty($_GET['to'])) { - $vars['to'] = $router['to']; + $vars['to'] = $_GET['to']; } - $vars['width'] = $router['width'] ?: 1075; - $vars['height'] = $router['height'] ?: 300; + $vars['width'] = $_GET['width'] ?: 1075; + $vars['height'] = $_GET['height'] ?: 300; $auth = "1"; $vars['id'] = dbFetchCell("SELECT `P`.`port_id` FROM `ports` AS `P` JOIN `devices` AS `D` ON `P`.`device_id` = `D`.`device_id` WHERE `D`.`hostname`=? AND `P`.`ifName`=?", array($hostname,$vars['port'])); $app->response->headers->set('Content-Type', 'image/png'); require("includes/graphs/graph.inc.php"); } -function get_port_stats_by_id() +function get_port_stats_by_port_hostname() { - // This will return port stats based on port id + // This will return port stats based on a devices hostname and ifName global $config; $app = \Slim\Slim::getInstance(); $router = $app->router()->getCurrentRoute()->getParams(); - $port_id = $router['id']; - $stats = dbFetchRow("SELECT * FROM `ports` WHERE `port_id`=?", array($port_id)); - $output = array("status" => "ok", "port" => $stats); - $app->response->headers->set('Content-Type', 'application/json'); - echo _json_encode($output); -} - -function get_port_stats_by_port() -{ - // This will return port stats based on ifName - global $config; - $app = \Slim\Slim::getInstance(); - $router = $app->router()->getCurrentRoute()->getParams(); - $device_id = $router['id']; - $if_name = $router['port']; - $stats = dbFetchRow("SELECT * FROM `ports` WHERE `device_id`=? AND `ifName`=?", array($device_id,$if_name)); + $ifName = $router['ifname']; + $stats = dbFetchRow("SELECT * FROM `ports` WHERE `ifName`=?", array($ifName)); $output = array("status" => "ok", "port" => $stats); $app->response->headers->set('Content-Type', 'application/json'); echo _json_encode($output); } -function get_graph_generic_by_deviceid() -{ - // This will return a graph type given a device id. - global $config; - $app = \Slim\Slim::getInstance(); - $router = $app->router()->getCurrentRoute()->getParams(); - $vars = array(); - $vars['device'] = $router['id']; - $vars['type'] = $router['type'] ?: 'port_bits'; - if(!empty($router['from'])) - { - $vars['from'] = $router['from']; - } - if(!empty($router['to'])) - { - $vars['to'] = $router['to']; - } - $vars['width'] = $router['width'] ?: 1075; - $vars['height'] = $router['height'] ?: 300; - $auth = "1"; - $app->response->headers->set('Content-Type', 'image/png'); - require("includes/graphs/graph.inc.php"); -} - function get_graph_generic_by_hostname() { // This will return a graph type given a device id. @@ -318,17 +230,17 @@ function get_graph_generic_by_hostname() $router = $app->router()->getCurrentRoute()->getParams(); $hostname = $router['hostname']; $vars = array(); - $vars['type'] = $router['type'] ?: 'port_bits'; - if(!empty($router['from'])) + $vars['type'] = $router['type'] ?: 'device_uptime'; + if(!empty($_GET['from'])) { - $vars['from'] = $router['from']; + $vars['from'] = $_GET['from']; } - if(!empty($router['to'])) + if(!empty($_GET['to'])) { - $vars['to'] = $router['to']; + $vars['to'] = $_GET['to']; } - $vars['width'] = $router['width'] ?: 1075; - $vars['height'] = $router['height'] ?: 300; + $vars['width'] = $_GET['width'] ?: 1075; + $vars['height'] = $_GET['height'] ?: 300; $auth = "1"; $vars['device'] = dbFetchCell("SELECT `D`.`device_id` FROM `devices` AS `D` WHERE `D`.`hostname`=?", array($hostname)); $app->response->headers->set('Content-Type', 'image/png'); @@ -341,8 +253,8 @@ function list_devices() global $config; $app = \Slim\Slim::getInstance(); $router = $app->router()->getCurrentRoute()->getParams(); - $order = $router['order']; - $type = $router['type']; + $order = $_GET['order']; + $type = $_GET['type']; if(empty($order)) { $order = "hostname"; diff --git a/html/pages/api-docs.inc.php b/html/pages/api-docs.inc.php index ff122e375..78f998e93 100644 --- a/html/pages/api-docs.inc.php +++ b/html/pages/api-docs.inc.php @@ -23,11 +23,13 @@ if ($_SESSION['userlevel'] == '10')

Introduction

The API is designed to enable you to interact with your installtion from other systems, monitoring systems, apps or websites using any programming language that can make a web request and both send and receive json data. This documentation will provide you the methods, accepted parameters and responses from the API.

+

Token authentication

Authentication against the API is done by tokens which are assigned to a user account. You can view and create tokens using the API access link within the System > API menu.


To send the token to the API you need to do this by using the X-Auth-Token within the header. As example if your API token was 91c60e737e342c205be5bba8e2954d27 then you would send the following X-Auth-Token: 91c60e737e342c205be5bba8e2954d27. As an example using curl within PHP you would do something like this:

curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth-Token: 91c60e737e342c205be5bba8e2954d27'));
+

API Responses

The following responses are standard across each request type except for where an image would be returned directly, the response will be output in json format:

status
@@ -37,93 +39,8 @@ if ($_SESSION['userlevel'] == '10') message

This will contain the reason for the success or failure of the request.


-

As an example to get you started quickly, here we use the API to request to list all devices:

-
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" "https://librenms.example.com/api/v1/list/devices"
-{ 
-  "status": "ok", 
-  "devices": [  
-  {
-   "device_id": "4",
-   "hostname": "example.co.uk",
-   "sysName": "example.co.uk",
-   "community": "public",
-   "authlevel": null,
-   "authname": null,
-   "authpass": null,
-   "authalgo": null,
-   "cryptopass": null,
-   "cryptoalgo": null,
-   "snmpver": "v1",
-   "port": "161",
-   "transport": "udp",
-   "timeout": null,
-   "retries": null,
-   "bgpLocalAs": null,
-   "sysObjectID": null,
-   "sysDescr": "Linux example.co.uk 2.6.18-238.19.1.el5 #1 SMP Fri Jul 15 07:31:24 EDT 2011 x86_64",
-   "sysContact": "root@localhost",
-   "version": "2.6.18-238.19.1.el5",
-   "hardware": "Generic x86 64-bit",
-   "features": null,
-   "location": "Unknown",
-   "os": "linux",
-   "status": "1",
-   "ignore": "0",
-   "disabled": "0",
-   "uptime": "90741309",
-   "agent_uptime": "0",
-   "last_polled": "2014-07-16 17:40:04",
-   "last_polled_timetaken": "2.16",
-   "last_discovered_timetaken": "3.15",
-   "last_discovered": "2014-07-16 12:33:44",
-   "purpose": "",
-   "type": "server",
-   "serial": null,
-   "icon": null
-  },
-  {
-   "device_id": "24",
-   "hostname": "localhost",
-   "sysName": "testing",
-   "community": "public",
-   "authlevel": "noAuthNoPriv",
-   "authname": "",
-   "authpass": "",
-   "authalgo": "MD5",
-   "cryptopass": "",
-   "cryptoalgo": "AES",
-   "snmpver": "v1",
-   "port": "161",
-   "transport": "udp",
-   "timeout": null,
-   "retries": null,
-   "bgpLocalAs": null,
-   "sysObjectID": null,
-   "sysDescr": "Linux testing 2.6.32-431.el6.x86_64 #1 SMP Fri Nov 22 03:15:09 UTC 2013 x86_64",
-   "sysContact": "root@localhost",
-   "version": "2.6.32-431.el6.x86_64",
-   "hardware": "Generic x86 64-bit",
-   "features": null,
-   "location": "Unknown",
-   "os": "linux",
-   "status": "1",
-   "ignore": "0",
-   "disabled": "0",
-   "uptime": "19355163",
-   "agent_uptime": "0",
-   "last_polled": "2014-07-16 17:40:04",
-   "last_polled_timetaken": "1.74",
-   "last_discovered_timetaken": "1.28",
-   "last_discovered": "2014-07-16 12:33:25",
-   "purpose": null,
-   "type": "server",
-   "serial": null,
-   "icon": null
-  }
- ]
-}
-    
+

API request types

The following request types are currently used:

+

Available requests

@@ -140,21 +58,21 @@ if ($_SESSION['userlevel'] == '10') - - + + - + - - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - + - - + - + - + + + + + - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -313,16 +137,16 @@ if ($_SESSION['userlevel'] == '10') - + + - + - - + - + + - + - - + - +
Version Path (required)Path (additional)Variables / JSON DataAdditional variables / JSON Data Returns
Port GraphsPort Graphs
/api /v1/get/graph/port/id/$id/$type/$width/$height/$from/$to/devices/$hostname/ports/$ifName/$type
    -
  • $id = the ID of the port
  • +
  • $hostname = the hostname of the device you want the graph for
  • +
  • $ifName = The ifName of the interface you want a graph for
  • $type = the type of graph for the port (port_bits,port_upkts)
  • $width = the width of the graph to be returned
  • $height = the height of the graph to be returned
  • @@ -167,74 +85,22 @@ if ($_SESSION['userlevel'] == '10')
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/id/1" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices/localhost/ports/eth0/port_bits" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/id/1/port_bits/1024/768/1405457456/1405543856" > /tmp/graph.png
/api/v1/get/graph/port/device/$device_id/$ifName/$type/$width/$height/$from/$to -
    -
  • $device_id = the ID of the device
  • -
  • $ifName = the ifName of an interface
  • -
  • $type = the type of graph for the port (port_bits,port_upkts)
  • -
  • $width = the width of the graph to be returned
  • -
  • $height = the height of the graph to be returned
  • -
  • $from = the from date/time of the graph (unix timestamp)
  • -
  • $to = the to date/time of the graph (unix timestamp)
  • -
-
- PNG Image -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/device/1/eth0" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/device/1/eth0/port_bits/1024/768/1405457456/1405543856" > /tmp/graph.png
/api/v1/get/graph/port/hostname/$hostname/$ifName/$type/$width/$height/$from/$to -
    -
  • $hostname = the hostname of the device
  • -
  • $ifName = the ifName of an interface
  • -
  • $type = the type of graph for the port (port_bits,port_upkts)
  • -
  • $width = the width of the graph to be returned
  • -
  • $height = the height of the graph to be returned
  • -
  • $from = the from date/time of the graph (unix timestamp)
  • -
  • $to = the to date/time of the graph (unix timestamp)
  • -
-
- PNG Image -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/hostname/localhost/eth0" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/port/hostname/localhost/eth0/port_bits/1024/768/1405457456/1405543856" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices/localhost/ports/eth0/port_bits?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png
General GraphsGeneral Graphs
/api /v1/get/graph/general/device/$device_id/$type/$width/$height/$from/$to/devices/$hostname/$type
    -
  • $device_id = the ID of the device
  • +
  • $hostname = the hostname of the device you want the graph for
  • $type = the type of graph for the device (device_processor,device_storage)
  • $width = the width of the graph to be returned
  • $height = the height of the graph to be returned
  • @@ -247,64 +113,22 @@ if ($_SESSION['userlevel'] == '10')
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/general/device/1/device_processor" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices/localhost/device_processor" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/general/device/1/device_processor/1024/768/1405457456/1405543856" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices/localhost/device_processor?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png
Port Stats
/api /v1/get/graph/general/hostname/$hostname/$type/$width/$height/$from/$to/devices/$hostname/ports/$ifName
  • $hostname = the hostname of the device
  • -
  • $type = the type of graph for the device (device_processor,device_storage)
  • -
  • $width = the width of the graph to be returned
  • -
  • $height = the height of the graph to be returned
  • -
  • $from = the from date/time of the graph (unix timestamp)
  • -
  • $to = the to date/time of the graph (unix timestamp)
  • -
-
- PNG Image -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/general/hostname/localhost/device_processor" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/graph/general/hostname/localhost/device_processor/1024/768/1405457456/1405543856" > /tmp/graph.png
Port Stats
/api/v1/get/stats/port/id/$port_id -
    -
  • $port_id = the ID of the port
  • -
-
- JSON -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/stats/port/id/1"
/api/v1/get/stats/port/device/$device_id/$ifName -
    -
  • $device_id = the ID of the device
  • $ifName = the ifName of the port
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/get/stats/port/device/1/eth0"
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices/localhost/ports/eth0"
ListList
/api /v1 /list/devices/$order/$type
  • $order = the name of the column to order by
  • @@ -334,19 +158,19 @@ if ($_SESSION['userlevel'] == '10')
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/list/devices"
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices"
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/list/devices/hostname/all"
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices?order=hostname&type=all"
AddAdd
/api /v1/add/device/devices
  • hostname = the hostname to be added
  • @@ -367,7 +191,7 @@ if ($_SESSION['userlevel'] == '10')
curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' \
-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/add/device"
curl -X POST -d '{"hostname":"localhost.localdomain","version":"v1","community":"public"}' \
-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v1/devices"
@@ -386,6 +210,7 @@ if ($_SESSION['userlevel'] == '10')
  • General Graphs
  • Port Stats
  • List
  • +
  • Add