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 | |
/devices/ /devices/<device_id> /devices/<hostname> |
Fetch Devices | group sysname location , os , version , features , type , status , ignore , disabled , graph |
/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 |
/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) |
/address/ |
Fetch IPv4/6 | af (ipv4, ipv6), device_id , port_id |
/entity/<entity_type>/<entity_id> |
Fetch Entity |
The /entity/
GET endpoint is provided as a generic method to retrieve any entity's database entry.
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 |
snmp_version | SNMP version in use, v1, v2c (default) or v3 |
snmp_port | SNMP port (default: 161) |
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) |
snmp_cryptopass | SNMP v3 Encryption Password |
snmp_cryptoalgo | SNMP v3 Encryption Algorithm (aes / des) |
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 their ignore
ignore_until
and disabled
attributes set 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 |
disabled | Disables polling the device ( 0 or 1 ) |
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 |