mirror of
https://github.com/librenms/librenms.git
synced 2024-09-25 04:19:07 +00:00
292 lines
12 KiB
PHP
292 lines
12 KiB
PHP
<?php
|
|
|
|
/*
|
|
* LibreNMS
|
|
*
|
|
* Copyright (c) 2014 Neil Lathwood <https://github.com/laf/ http://www.lathwood.co.uk/fa>
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License as published by the
|
|
* Free Software Foundation, either version 3 of the License, or (at your
|
|
* option) any later version. Please see LICENSE.txt at the top level of
|
|
* the source code distribution for details.
|
|
*/
|
|
|
|
if ($_SESSION['userlevel'] == '10')
|
|
{
|
|
|
|
?>
|
|
|
|
<div class="row">
|
|
<div class="col-sm-9">
|
|
<a name="intro"></a>
|
|
<h3>Introduction</h3>
|
|
<p>The API is designed to enable you to interact with your <?php echo $config['project_name'];?> 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.</p>
|
|
<a name="tokens"></a>
|
|
<hr><br />
|
|
<h3>Token authentication</h3>
|
|
<p>Authentication against the API is done by tokens which are assigned to a user account. You can view and create tokens using the <a href="api-access">API access</a> link within the System > API menu.</p><br />
|
|
<p>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:</p>
|
|
<code>curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth-Token: 91c60e737e342c205be5bba8e2954d27'));</code><br />
|
|
<a name="responses"></a>
|
|
<hr><br />
|
|
<h3>API Responses</h3>
|
|
<p>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:</p>
|
|
<strong>status</strong><br />
|
|
<ul class="list-unstyled">
|
|
<li>ok = The request was successful</li>
|
|
<li>error = The request failed</li>
|
|
</ul>
|
|
<strong>message</strong><br />
|
|
<p>This will contain the reason for the success or failure of the request.</p><br />
|
|
<a name="request-types"></a>
|
|
<hr><br />
|
|
<h3>API request types</h3>
|
|
<p>The following request types are currently used:</p>
|
|
<ul class="list-unstyled">
|
|
<li><strong>GET</strong> - This is used for the retrieval of information or images.</li>
|
|
<li><strong>POST</strong> - This is used for adding new items such as devices.</li>
|
|
<li><strong>PUT</strong> - This is used to update existing items.</li>
|
|
<li><strong>DELETE</strong> - This is used to remove items.</li>
|
|
</ul>
|
|
<a name="requests"></a>
|
|
<hr><br />
|
|
<h3>Available requests</h3>
|
|
<div class="table-responsive">
|
|
<table class="table table-bordered table-hover table-condensed">
|
|
<tr>
|
|
<th></th>
|
|
<th>Version</th>
|
|
<th>Path (required)</th>
|
|
<th>Additional variables / JSON Data</th>
|
|
<th>Returns</th>
|
|
</tr>
|
|
<a name="port_graphs"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>Port Graphs</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname/ports/$ifName/$type</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>$hostname = the hostname of the device you want the graph for</li>
|
|
<li>urlencode($ifName) = The ifName of the interface you want a graph for</li>
|
|
<li>$type = the type of graph for the port (port_bits,port_upkts)</li>
|
|
<li>$width = the width of the graph to be returned</li>
|
|
<li>$height = the height of the graph to be returned</li>
|
|
<li>$from = the from date/time of the graph (unix timestamp)</li>
|
|
<li>$to = the to date/time of the graph (unix timestamp)</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
PNG Image
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0/port_bits" > /tmp/graph.png</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0/port_bits?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
|
|
</tr>
|
|
<a name="general_info"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>General Info</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>$hostname = the hostname of the device you want the information about</li>
|
|
</ul>
|
|
</td>
|
|
<td>JSON</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost" > localhost.json</code></td>
|
|
</tr>
|
|
<a name="general_graphs"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>General Graphs</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname/$type</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>$hostname = the hostname of the device you want the graph for</li>
|
|
<li>$type = the type of graph for the device (device_processor,device_storage)</li>
|
|
<li>$width = the width of the graph to be returned</li>
|
|
<li>$height = the height of the graph to be returned</li>
|
|
<li>$from = the from date/time of the graph (unix timestamp)</li>
|
|
<li>$to = the to date/time of the graph (unix timestamp)</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
PNG Image
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/device_processor" > /tmp/graph.png</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/device_processor?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png</code></td>
|
|
</tr>
|
|
<a name="port_stats"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>Port Stats</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname/ports/$ifName</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>$hostname = the hostname of the device</li>
|
|
<li>urlencode($ifName) = the ifName of the port</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
JSON
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/ports/eth0"</code></td>
|
|
</tr>
|
|
<a name="list"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>List</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>$order = the name of the column to order by</li>
|
|
<li>$type = this is the device status (all, ignored, up, down, disabled)</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
JSON
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices"</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices?order=hostname&type=all"</code></td>
|
|
</tr>
|
|
<a name="add"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>Add</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>hostname = the hostname to be added</li>
|
|
<li>version = the version of snmp to use</li>
|
|
<li>community = the community to use</li>
|
|
<li>port = the port to use</li>
|
|
<li>transport = the transport to use</li>
|
|
<li>authlevel = the auth level to use for v3</li>
|
|
<li>authname = the auth name to use for v3</li>
|
|
<li>authpass = the auth pass to use for v3</li>
|
|
<li>authalog = the auth algorythm to use for v3</li>
|
|
<li>cryptopass = the crypto pass to use for v3</li>
|
|
<li>cryptoalgo = the crytpo algo to use for v3</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
JSON
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -X POST -d '{"hostname":"localhost.localdomain","version":"v0","community":"public"}' \<br />-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices"</code></td>
|
|
</tr>
|
|
<a name="delete"></a>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>Delete</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>hostname = the hostname to be deleted</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
JSON
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost"</code></td>
|
|
</tr>
|
|
<tr class="success">
|
|
<td colspan="5"><strong>List VLANs</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td>/api</td>
|
|
<td>/v0</td>
|
|
<td>/devices/$hostname/vlans</td>
|
|
<td>
|
|
<ul class="list-unstyled">
|
|
<li>hostname = the hostname to list vlans for</li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
JSON
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="5"><code>curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \<br/> "https://librenms.example.com/api/v0/devices/localhost/vlans"</code></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="col-sm-3">
|
|
<div class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="sidebar" role="complementary">
|
|
<ul class="nav bs-docs-sidenav">
|
|
<li><a href="api-docs/#intro">Introduction</a></li>
|
|
<li><a href="api-docs/#tokens">Token authentication</a></li>
|
|
<li><a href="api-docs/#responses">API responses</a></li>
|
|
<li><a href="api-docs/#request-types">API request types</a></li>
|
|
<li>
|
|
<a href="api-docs/#requests">Available requests</a>
|
|
<ul class="nav">
|
|
<li><a href="api-docs/#port_graphs">Port Graphs</a></li>
|
|
<li><a href="api-docs/#general_graphs">General Graphs</a></li>
|
|
<li><a href="api-docs/#port_stats">Port Stats</a></li>
|
|
<li><a href="api-docs/#list">List</a></li>
|
|
<li><a href="api-docs/#add">Add</a></li>
|
|
<li><a href="api-docs/#delete">Delete</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
$('#sidebar').affix({
|
|
offset: {
|
|
top: $('header').height()
|
|
}
|
|
});
|
|
</script>
|
|
<?php
|
|
|
|
} else {
|
|
include("includes/error-no-perm.inc.php");
|
|
}
|
|
|
|
?>
|