API
Observium includes a structured REST/JSON-based API designed to facilitate access to data held in Observium's MySQL database. An additional graphing API is available to generate graphs from Observium's RRDtool-based metrics.
Active Development
The API is currently in active development. We're still creating its specification and deciding what should be included and what features will be added. If you'd like to be involved in this process, please join our IRC channel where most development discussion takes place.
Subscription Feature
This is a feature which is currently only included in the Subscription Edition of Observium.
Enabling
The API is enabled by adding the following configuration option to config.php :
$config['api']['enable'] = TRUE;
Authentication
Currently the API supports HTTP basic authentication to an existing Observium user. This allows the API to be authenticated against any existing authentication system including LDAP, RADIUS and Observium's own MySQL authentication database.
Authentication is simple, for example:
curl -u <username>:<password> http://observium.domain.com/api/v0/devices/
Basic Operation
The API has the basic URL structure of /api/<version>/<entity>/<entity_id>/<query>
. Both the Entity ID and Query are optional. The query format matches the same as that used by the Web UI, so many of the same options and filters can be used.
For example:
To request a list of all devices
GET /api/v0/devices/
To request a data array for device with the id 1
GET /api/v0/devices/1/
Some entity types allow text-based ids, for example to request a data array for the device test.company.com
:
GET /api/v0/devices/test.company.com/
Using the query options is simple too, for example to request all devices with the os ios
:
GET /api/v0/devices/?os=ios
The output from this query would look like this :
{
"status": "ok",
"count": 2,
"devices": {
"277": {
"device_id": "277",
"hostname": "router-1.company.com",
"sysObjectID": ".1.3.6.1.4.1.9.1.620",
"sysDescr": "Cisco IOS Software, 1841 Software (C1841-IPBASE-M), Version 15.0(1)M4, RELEASE SOFTWARE (fc1)\r\nTechnical Support: http://www.cisco.com/techsupport\r\nCopyright
(c) 1986-2010 by Cisco Systems, Inc.\r\nCompiled Thu 28-Oct-10 15:40 by prod_rel_team",
"version": "15.0(1)M4",
"hardware": "CISCO1841",
"features": "IPBASE",
"os": "ios",
...
<most device data removed for brevity>
},
"278": {
"device_id": "278",
"hostname": "router-b.company.com", }
"sysObjectID": ".1.3.6.1.4.1.9.1.620",
"sysDescr": "Cisco IOS Software, 1841 Software (C1841-IPBASE-M), Version 15.0(1)M4, RELEASE SOFTWARE (fc1)\r\nTechnical Support: http://www.cisco.com/techsupport\r\nCopyright
(c) 1986-2010 by Cisco Systems, Inc.\r\nCompiled Thu 28-Oct-10 15:40 by prod_rel_team",
"version": "15.0(1)M4",
"hardware": "CISCO1841",
"features": "IPBASE",
"os": "ios",
...
<most device data removed for brevity>
}
}
}
GET Endpoints
GET endpoints are used to retrieve information from Observium.
Endpoint | Description | Options |
---|---|---|
/alerts/ /alerts/<alert_id> |
Fetch Alerts | device_id , status (failed/failed_suppressed/delayed), entity_type , entity_id , alert_test_id |
/alert_checks/ |
Fetch Alert Checks | |
/address/ |
Fetch IPv4/6 | af (ipv4, ipv6), device_id , port_id |
/counters/ |
Fetch Counter | group_id , device_id , counter_id , entity_id (measured entity), entity_type (measured entity type), entity_state (measured entity state), counter_class , counter_descr , counter_event |
/devices/ /devices/<device_id> /devices/<hostname> |
Fetch Devices | group sysname location , os , version , features , type , status , ignore , disabled , graph |
/entity/<entity_type>/<entity_id>/ |
Fetch Single Entity | |
/inventory/ |
Fetch entPhysical | device_id , os , entPhysicalModelName , entPhysicalSerialNum , entPhysicalDescr , entPhysicalClass , deleted (0/1) |
/mempools/ |
Fetch Mempools | group_id device_id mempool_descr |
/neighbours/ |
Fetch Neighbours | device_id , device_b , port_id , port_b , protocol , platform , version , active , remote_port_id |
/ports/ /ports/<port_id> |
Fetch Ports | location , device_id , group , disable , deleted , ignore , ifSpeed , ifType , hostname , ifAlias , ifDescr , port_descr_type , errors (yes), alerted (yes), state (down, up, admindown, shutdown), cbqos , mac_accounting |
/printersupplies/ |
Fetch Printer Supplies | group_id , device_id , supply_type , supply_colour , supply_descr |
/processors/ |
Fetch Processor | group_id , device_id , processor_descr |
/sensors/ |
Fetch Sensors | metric group group_id device_id entity_id entity_type sensor_descr sensor_type id event (ok, alert, warn, ignore) |
/status/ |
Fetch Status | group_id device_id id class event (ok, alert, warn, ignore) |
/storage/ |
Fetch Storage | group_id device_id storage_descr |
The /entity/
GET endpoint is provided as a generic method to retrieve any entity's database entry. This can be used to fetch any single entity entry, for example /entity/port/2342
would fetch the entry for a port with the port_id
of 2342.
Field Filtering
Some endpoints allow filtering the results by field, for example by returning only the port_id
and port_label
fields for a /ports/
query. This can provide much better performance for large queries.
Filtering works by supplying a comma-separated list of fields via the fields
parameter.
Pagination
Some endpoints allow pagination of returned results using the pagesize
and pageno
parameters. Note that database content may change between API queries resulting in unreliable results.
Devices
Adding a Device
Adding devices is achived by using the POST
method on the /devices/
endpoint. This endpoint uses the same fields as used by the Web UI form. The endpoint will return a JSON array containing the device's id if it's successfully created.
At its most basic you need to provide a hostname for the device to be added. If the device can be reached via SNMP using one of the community strings in Observium's configuration, this should be sufficient.
For example:
root@srv:/home/observium/dev# curl -u user:pass http://localhost/api/v0/devices/ -H "Content-Type: application/json" -X POST -d '{"hostname":"localhost"}'
{"status":"ok","device_id":1}
root@srv:/home/observium/dev#
More complex scenarios may require one additional arguments from the table below
Option | Description |
---|---|
hostname | Resolveable hostname or IP address |
poller_id | Distributed poller ID (available only for Enterprise Edition) |
ping_skip | Skip check device is Pingable: on (default) or off |
snmp_version | SNMP version in use: v1 , v2c (default) or v3 |
snmp_port | SNMP port (default: 161 ) |
snmp_timeout | SNMP timeout (default: 1 s) |
snmp_retries | SNMP retries (default: 5 ) |
snmp_community | SNMP community for use with SNMP v1 and v2c |
snmp_authlevel | SNMP v3 Auth Level (noAuthNoPriv / authNoPriv / authPriv ) |
snmp_authname | SNMP v3 Auth Username |
snmp_authpass | SNMP v3 Auth Password |
snmp_authalgo | SNMP v3 Auth Algorithm (md5 / sha / sha-224 / sha-256 / sha-384 / sha-512) |
snmp_cryptopass | SNMP v3 Encryption Password |
snmp_cryptoalgo | SNMP v3 Encryption Algorithm (des / aes / aes-192 / aes-192-c / aes-256 / aes-256-c) |
snmp_maxrep | SNMP Maximum Repetition (default: Empty, set 0 for disable) |
snmp_context | SNMP Context (default: Empty) |
Deleting a device
Deleting devices is performed using the DELETE
verb on the /devices/
endpoint with the device_id as the final path element.
For example:
root@srv:/opt/observium# curl -u user:pass http://observium/api/v0/devices/491/ -X DELETE
{"status":"ok","message":"Device Deleted","output":"\n * Deleted interfaces: id=393287 (eth0), id=393288 (eth1), id=393289 (eth2), id=393290 (eth3), id=393291 (eth4), id=393292 (eth5), id=393293 (eth6), id=393294 (eth7), id=393295 (eth8)\n * Deleted common entity entries linked to device: device\n * Deleted device entries from tables: alert_log, alert_table, devices_locations, devices_perftimes, device_graphs, eventlog, vlans, devices\n * Deleted device: test.domain.com"}
root@srv:/opt/observium#
Changing a device
Devices can have some attributes changed by using a PUT
method on the /devices/
endpoint.
Option | Description |
---|---|
ignore | Ignores the device for alerting ( 0 or 1 ) |
ignore_until | Ignores the device until the specified time in the format Y-m-d H:i:s , eg 2017-05-13 12:34:20 . "null" or blank unsets. |
disabled | Disables polling the device ( 0 or 1 ) |
purpose | Changes/unsets the Purpose/Description of the device. "null" or blank unsets. |
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/devices/47/ -H "Content-Type: application/json" -d '{"disable":"1"}'
{"status":"updated","message":"Device 47 updated."}
root@omega:~#
Alert Entries
Ignoring an alert entry
Alerts can have their ignore_until_ok
and ignore_until
attributes set by using the PUT
method on the /alerts/
endpoint.
For example, this would set the alert to be ignored until it was next found to be ok and also ignored until 12:34:20 on 13th May 2017:
root@omega:~# curl -u user:password -X PUT http://observium/api/v0/alerts/48467/ -H "Content-Type: application/json" -d '{"ignore_until_ok":"1", "ignore_until":"2017-05-13 12:34:20"}'
{"status":"updated","message":"Alert 48467 updated."}
root@omega:~#
Option | Description |
---|---|
ignore_until_ok |
Ignores the alert until it is OK. (0 or 1 ) |
ignore_until |
Ignores the alert until the time specified in the format Y-m-d H:i:s , eg 2017-05-13 12:34:20 |