Skip to content

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: 1s)
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