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