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')
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.
+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'));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:
statusThis 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
- }
- ]
-}
-
+ The following request types are currently used: