From 9d1fd5adb48324f6a06e9844eb953b016485b207 Mon Sep 17 00:00:00 2001 From: laf Date: Tue, 23 Dec 2014 16:35:09 +0000 Subject: [PATCH] Updated location of API docs --- html/includes/print-menubar.php | 2 +- html/pages/api-docs.inc.php | 387 +------------------------------- 2 files changed, 6 insertions(+), 383 deletions(-) diff --git a/html/includes/print-menubar.php b/html/includes/print-menubar.php index 43090f279..f0e07e54e 100644 --- a/html/includes/print-menubar.php +++ b/html/includes/print-menubar.php @@ -452,7 +452,7 @@ if ($_SESSION['userlevel'] >= '10') API '); } ?> diff --git a/html/pages/api-docs.inc.php b/html/pages/api-docs.inc.php index 612d9e107..c260b73ce 100644 --- a/html/pages/api-docs.inc.php +++ b/html/pages/api-docs.inc.php @@ -12,390 +12,13 @@ * the source code distribution for details. */ -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
-
    -
  • ok = The request was successful
    • -
  • error = The request failed
    • -
- message
-

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


- -

-

API request types

-

The following request types are currently used:

-
    -
  • GET - This is used for the retrieval of information or images.
    • -
  • POST - This is used for adding new items such as devices.
    • -
  • PUT - This is used to update existing items.
    • -
  • DELETE - This is used to remove items.
    • -
- -

-

Available requests

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VersionPath (required)Additional variables / JSON DataReturns
Port Graphs
/api/v0/devices/$hostname/ports/$ifName/$type -
    -
  • $hostname = the hostname of the device you want the graph for
    • -
  • urlencode($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
    • -
  • $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/v0/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/v0/devices/localhost/ports/eth0/port_bits?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png
General Info
/api/v0/devices/$hostname -
    -
  • $hostname = the hostname of the device you want the information about
    • -
- 		JSON
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost" > localhost.json
General Graphs
/api/v0/devices/$hostname/$type -
    -
  • $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
    • -
  • $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/v0/devices/localhost/device_processor" > /tmp/graph.png
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost/device_processor?width=1024&height=768&from=1405457456&to=1405543856" > /tmp/graph.png
Port Stats
/api/v0/devices/$hostname/ports/$ifName -
    -
  • $hostname = the hostname of the device
    • -
  • urlencode($ifName) = the ifName of the port
    • -
- 		- JSON -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost/ports/eth0"
Graphs by portgroup
/api/v0/portgroups/$group -
    -
  • $group = transit,peering,core (or multiple separated by comma)
    • -
  • $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)
    • -
  • $legend = Enable or disable the graph legend (yes/no)
    • -
- 		- image/png -
curl -H "Content-Type: image/png" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/portgroups/peering"
curl -H "Content-Type: image/png" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/portgroups/peering,transit?width=1024&height=768&from=1405457456&to=1405543856&legend=no"
List
/api/v0/devices -
    -
  • $order = the name of the column to order by
    • -
  • $type = this is the device status (all, ignored, up, down, disabled)
    • -
- 		- JSON -
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices"
curl -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices?order=hostname&type=all"
Add
/api/v0/devices -
    -
  • hostname = the hostname to be added
    • -
  • version = the version of snmp to use
    • -
  • community = the community to use
    • -
  • port = the port to use
    • -
  • transport = the transport to use
    • -
  • authlevel = the auth level to use for v3
    • -
  • authname = the auth name to use for v3
    • -
  • authpass = the auth pass to use for v3
    • -
  • authalog = the auth algorythm to use for v3
    • -
  • cryptopass = the crypto pass to use for v3
    • -
  • cryptoalgo = the crytpo algo to use for v3
    • -
- 		- JSON -
curl -X POST -d '{"hostname":"localhost.localdomain","version":"v0","community":"public"}' \
-H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices"
Delete
/api/v0/devices/$hostname -
    -
  • hostname = the hostname to be deleted
    • -
- 		- JSON -
curl -X DELETE -H "Content-Type: application/json" -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost"
List VLANs
/api/v0/devices/$hostname/vlans -
    -
  • hostname = the hostname to list vlans for
    • -
- 		- JSON -
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost/vlans"
List BGP Sessions
/api/v0/bgp -
    -
- 		- JSON -
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/bgp"
List ports for a device
/api/v0/devices/$hostname/ports -
    -
  • hostname = the hostname to list vlans for
    • -
  • columns = the columns to return in the response
    • -
- 		- JSON -
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost/ports"
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/devices/localhost/ports?columns=ifDescr,ifName"
List Bills
/api/v0/bills -
    -
  • custid = the customer reference for the bill
    • -
  • ref = the billing reference for the bill
    • -
- 		- JSON -
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/bills"
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/bills?custid=Testing"
Retrieve Bill information
/api/v0/bills/$bill_id -
    -
- 		- JSON -
curl -H "X-Auth-Token: 91c60e737e342c205be5bba8e2954d27" \
"https://librenms.example.com/api/v0/bills/$bill_id"
-
-
-
- -
-
- +
here.'); ?> +
+ +