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.

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 13^th 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`