From OpenNMS

Jump to: navigation, search

A RESTful interface is a web service conforming to the REST architectural style as described in the book RESTful Web Services. This page is describes the work being done to develop a RESTful interface for opennms.

ReST URL

The base URL for Rest Calls is : http://opennmsserver:8980/opennms/rest/

For instance, http://localhost:8980/opennms/rest/alarms/ will give you the current alarms in the system.

Data format

Jersey allows ReST calls to be made using either XML or JSON.

By default a request to the API is returned in XML. To get JSON encoded responses one has to send the following header with the request: "Accept: application/json".

Standard Params

The following are standard params which are available on most resources (noted below)

limit - integer, limiting the number of results. This is particularly handy on events and notifications, where an accidental call with no limit could result in many thousands of results being returned, killing either the client or the server. If set to 0, then no limit applied
offset - integer, being the numeric offset into the result set from which results should start being returned. E.g., if there are 100 result entries, offset is 15, and limit is 10, then entries 15-24 will be returned. Used for pagination
Filtering: All properties of the entity being accessed can be specified as parameters in either the URL (for GET) or the form value (for PUT and POST). If so, the value will be used to add a filter to the result. By default, the operation is equality, unless the "comparator" parameter is sent, in which case it applies to *all* comparisons in the filter. Multiple properties will result in an "AND" operation between the filter elements. Available comparators are:
- eq Checks for equality
- ne Checks for non-equality
- ilike Case-insensitive wildcarding (% is the wildcard)
- like Case-sensitive wildcarding (% is the wildcard)
- gt Greater than
- lt Less than
- ge Greater than or equal
- le Less than or equal

If the value "null" is passed for a given property, then the obvious operation will occur (comparator will be ignored for that property).
"notnull" is handled similarly.

Ordering: If the parameter "orderBy" is specified, results will be ordered by the named property. Default is ascending, unless the "order" parameter is set to "desc" (any other value will default to ascending)

Raw where clause: If there is a "query" parameter, it will be used as a raw where clause (SQL, not HQL), and added to any other filters created by other parameters

Standard filter examples

Take /events as an example.

/events?eventUei=uei.opennms.org/internal/rtc/subscribe

would return the first 10 events with the rtc subscribe UEI, (10 being the default limit for events)

/events?eventUei=uei.opennms.org/internal/rtc/subscribe&limit=0

would return *all* the rtc subscribe events (potentially quite a few)

/events?id=100&comparator=gt

would return the first 10 events with an id greater than 100

/events?eventAckTime=notnull

would return the first 10 events that have a non-null Ack time (i.e. those that have been acknowledged)

/events?eventAckTime=notnull&id=100&comparator=gt&limit=20

would return the first 20 events that have a non-null Ack time and an id greater than 100. Note that the notnull value causes the comparator to be ignored for eventAckTime

/events?eventAckTime=2008-07-28T04:41:30.530+12:00&id=100&comparator=gt&limit=20

would return the first 20 events that have were acknowledged after 28th July 2008 at 4:41am (+12:00), and an id greater than 100. Note that the same comparator applies to both property comparisons.

/events?orderBy=id&order=desc

would return the 10 latest events inserted (probably, unless you've been messing with the id's)

Currently Implemented Interfaces

Nodes

Note: the default offset is 0, the default limit is 10 results. To get all results, use limit=0 as a parameter on the URL (ie, GET /nodes?limit=0).

Additionally, anywhere you use "id" in the queries below, you an use the foreign source and foreign ID separated by a colon instead (ie, GET /nodes/fs:fid).

GETs (Reading Data)

/nodes: Get a list of nodes. This includes the ID and node label.
/nodes/{id}: Get a specific node, by ID.
/nodes/{id}/ipinterfaces: Get the list of IP interfaces associated with the given node.
/nodes/{id}/ipinterfaces/{ipAddress}: Get the IP interface for the given node and IP address.
/nodes/{id}/ipinterfaces/{ipAddress}/services: Get the list of services associated with the given node and IP interface.
/nodes/{id}/ipinterfaces/{ipAddress}/services/{service}: Get the requested service associated with the given node, IP interface, and service name.
/nodes/{id}/snmpinterfaces: Get the list of SNMP interfaces associated with the given node.
/nodes/{id}/snmpinterfaces/{ifIndex}: Get the specific interface associated with the given node and ifIndex.
/nodes/{id}/categories: Get the list of categories associated with the given node.
/nodes/{id}/categories/{categoryName}: Get the category associated with the given node and category name.
/nodes/{id}/assetRecord: Get the asset record associated with the given node.

POSTs (Adding Data)

POST requires XML using application/xml as its Content-Type.

/nodes: Add a node.
/nodes/{id}/ipinterfaces: Add an IP interface to the node.
/nodes/{id}/ipinterfaces/{ipAddress}/services: Add a service to the interface for the given node.
/nodes/{id}/snmpinterfaces: Add an SNMP interface to the node.
/nodes/{id}/categories: Add a category association to the node.

PUTs (Modifying Data)

PUT requires form data using application/x-www-form-urlencoded as a Content-Type.

/nodes/{id}: Modify a node with the given ID.
/nodes/{id}/ipinterfaces/{ipAddress}: Modify the IP interface with the given node ID and IP address.
/nodes/{id}/ipInterfaces/{ipAddress}/services/{service}: Modify the service with the given node ID, IP address, and service name.
/nodes/{id}/snmpinterfaces/{ifIndex}: Modify the SNMP interface with the given node ID and ifIndex.
/nodes/{id}/categories/{categoryName}: Modify the category with the given node ID and name.

DELETEs (Removing Data)

Perform a DELETE to the singleton URLs specified in PUTs above to delete that object.

Events

GETs (Reading Data)

/events: Get a list of events. The default for offset is 0, and the default for limit is 10. To get all results, use limit=0 as a parameter on the URL (ie, GET /events?limit=0).
/events/count: Get the number of events. (Returns plaintext, rather than XML or JSON.)
/events/{id}: Get the event specified by the given ID.

PUTs (Modifying Data)

PUT requires form data using application/x-www-form-urlencoded as a Content-Type.

/events/{id}?ack=(true|false): Acknowledges (or unacknowledges) an event.
/events?filter=...&ack=(true|false): Acknowledges (or unacknowledges) the matching events.

Alarms

Note: the default offset is 0, the default limit is 10 results. To get all results, use limit=0 as a parameter on the URL (ie, GET /events?limit=0).

GETs (Reading Data)

/alarms: Get a list of alarms.
/alarms/count: Get the number of alarms. (Returns plaintext, rather than XML or JSON.)
/alarms/{id}: Get the alarms specified by the given ID.

Note that you can also query by severity, like so:

/alarms?comparator=ge&severity=MINOR: Get the alarms with a severity greater than or equal to "MINOR".

PUTs (Modifying Data)

PUT requires form data using application/x-www-form-urlencoded as a Content-Type.

/alarms/{id}?ack=(true|false): Acknowledges (or unacknowledges) an alarm.
/alarms?filter=...&ack=(true|false): Acknowledges (or unacknowledges) the matching alarms.

Queries

As noted above, it is possible to pass a raw "query" parameter when doing ReST queries. In the case of alarms, it is possible to pass severity names when querying by severity, rather than having to know the number that the severity enum maps to. For example:

 /alarms?query=lastEventTime%20%3E%20'2011-08-19T11%3A11%3A11.000-07%3A00'%20AND%20severity%20%3E%20MAJOR%20AND%20alarmAckUser%20IS%20NULL

This will get any alarms where the last event associated with the alarm is newer than August 19th, 2011 11:11:11, the severity is greater than MAJOR, and the alarm is not acknowledged (alarmAckUser is null).

You should be able to use any column in the alarm, event, node, ipinterface, or snmpinterface tables.

Acknowledgements

Note: the default offset is 0, the default limit is 10 results. To get all results, use limit=0 as a parameter on the URL (ie, GET /acks?limit=0).

GETs (Reading Data)

/acks: Get a list of acknowledgements.
/acks/count: Get the number of acknowledgements. (Returns plaintext, rather than XML or JSON.)
/acks/{id}: Get the acknowledgement specified by the given ID.

POSTs (Setting Data)

/acks?alarmId=N: Creates an acknowledgement for the given alarm ID. Optionally takes an "action" parameter which can be one of ack, unack, clear, or esc (escalate).

/acks?notifId=N: Creates an acknowledgement for the given notification ID. Optionally takes an "action" parameter which can be one of ack, unack, clear, or esc (escalate).

Notifications

Note: the default offset is 0, the default limit is 10 results. To get all results, use limit=0 as a parameter on the URL (ie, GET /events?limit=0).

GETs (Reading Data)

/notifications: Get a list of notifications.
/notifications/count: Get the number of notifications. (Returns plaintext, rather than XML or JSON.)
/notifications/{id}: Get the notification specified by the given ID.

Outages

GETs (Reading Data)

/outages: Get a list of outages.
/outages/count: Get the number of outages. (Returns plaintext, rather than XML or JSON.)
/outages/{id}: Get the outage specified by the given ID.
/outages/forNode/{nodeId}: Get the outages that match the given node ID.

Requisitions

RESTful service to the OpenNMS Provisioning Groups. In this API, these "groups" of nodes are aptly named and treated as requisitions.

This current implementation supports CRUD operations for managing provisioning requisitions. Requisitions are first POSTed and no provisioning (import/synchronize) operations are taken. This is done so that a) the XML can be verified and b) so that the operations can happen at a later time. They are moved to the deployed state (put in the active requisition repository) when an import is run.

If a request says that it gets the "active" requisition, that means it returns the pending requisition (being edited for deployment) if there is one, otherwise it returns the deployed requisition.

Note that anything that says it adds/deletes/modifies a "node," "interface," etc. in these instructions is referring to modifying that element from the requisition not from the database itself. That will happen upon import/synchronization.

GETs (Reading Data)

/requisitions: Get all active requisitions.
/requisitions/count: Get the number of active requisitions. (Returns plaintext, rather than XML or JSON.)
/requisitions/deployed: Get the list of all deployed (active) requisitions.
/requisitions/deployed/count: Get the number of deployed requisitions. (Returns plaintext, rather than XML or JSON.)
/requisitions/{name}: Get the active requisition for the given foreign source name.
/requisitions/{name}/nodes: Get the list of nodes being requisitioned for the given foreign source name.
/requisitions/{name}/nodes/{foreignId}: Get the node with the given foreign ID for the given foreign source name.
/requisitions/{name}/nodes/{foreignId}/interfaces: Get the interfaces for the node with the given foreign ID and foreign source name.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}: Get the interface with the given IP for the node with the specified foreign ID and foreign source name.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}/services: Get the services for the interface with the specified IP address, foreign ID, and foreign source name.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}/services/{service}: Get the given service with the specified IP address, foreign ID, and foreign source name.
/requisitions/{name}/nodes/{foreignId}/categories: Get the categories for the node with the given foreign ID and foreign source name.
/requisitions/{name}/nodes/{foreignId}/categories/{categoryName}: Get the category with the given name for the node with the specified foreign ID and foreign source name.
/requisitions/{name}/nodes/{foreignId}/assets: Get the assets for the node with the given foreign ID and foreign source name.

POSTs (Adding Data)

/requisitions: Adds (or replaces) a requisition.
/requisitions/{name}/nodes: Adds (or replaces) a node in the specified requisition.
/requisitions/{name}/nodes/{foreignId}/interfaces: Adds (or replaces) an interface for the given node in the specified requisition.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}/services: Adds (or replaces) a service on the given interface in the specified requisition.
/requisitions/{name}/nodes/{foreignId}/categories: Adds (or replaces) a category for the given node in the specified requisition.
/requisitions/{name}/nodes/{foreignId}/assets: Adds (or replaces) an asset for the given node in the specified requisition.

PUTs (Modifying Data)

/requisitions/{name}/import: Performs an import/synchronize on the specified foreign source. This turns the "active" requisition into the "deployed" requisition.
/requisitions/{name}: Update the specified foreign source.
/requisitions/{name}/nodes/{foreignId}: Update the specified node for the given foreign source.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}: Update the specified IP address for the given node and foreign source.

DELETEs (Removing Data)

/requisitions/{name}: Delete the pending requisition for the named foreign source.
/requisitions/deployed/{name}: Delete the active requisition for the named foreign source.
/requisitions/{name}/nodes/{foreignId}: Delete the node with the given foreign ID from the given requisition.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}: Delete the IP address from the requisitioned node with the given foreign ID and foreign source.
/requisitions/{name}/nodes/{foreignId}/interfaces/{ipAddress}/services/{service}: Delete the service from the requisitioned interface with the given IP address, foreign ID and foreign source.
/requisitions/{name}/nodes/{foreignId}/categories/{category}: Delete the category from the node with the given foreign ID and foreign source.
/requisitions/{name}/nodes/{foreignId}/assets/{field}: Delete the field from the requisition's nodes asset with the given foreign ID and foreign source.

Foreign Sources

ReSTful service to the OpenNMS Provisioning Foreign Source definitions. Foreign source definitions are used to control the scanning (service detection) of services for SLA monitoring as well as the data collection settings for physical interfaces (resources).

This API supports CRUD operations for managing the Provisioner's foreign source definitions. Foreign source definitions are POSTed and will be deployed when the corresponding requisition (provisioning group) gets imported/synchronized by provisiond.

If a request says that it gets the "active" foreign source, that means it returns the pending foreign source (being edited for deployment) if there is one, otherwise it returns the deployed foreign source.

GETs (Reading Data)

/foreignSources: Get all active foreign sources.
/foreignSources/default: Get the active default foreign source.
/foreignSources/deployed: Get the list of all deployed (active) foreign sources.
/foreignSources/deployed/count: Get the number of deployed foreign sources. (Returns plaintext, rather than XML or JSON.)
/foreignSources/{name}: Get the active foreign source named {name}.
/foreignSources/{name}/detectors: Get the configured detectors for the foreign source named {name}.
/foreignSources/{name}/detectors/{detector}: Get the specified detector for the foreign source named {name}.
/foreignSources/{name}/policies: Get the configured policies for the foreign source named {name}.
/foreignSources/{name}/policies/{policy}: Get the specified policy for the foreign source named {name}.

POSTs (Adding Data)

POST requires XML using application/xml as its Content-Type.

/foreignSources: Add a foreign source.
/foreignSources/{name}/detectors: Add a detector to the named foreign source.
/foreignSources/{name}/policies: Add a policy to the named foreign source.

PUTs (Modifying Data)

PUT requires form data using application/x-www-form-urlencoded as a Content-Type.

/foreignSources/{name}: Modify a foreign source with the given name.

DELETEs (Removing Data)

/foreignSources/{name}: Delete the named foreign source.
/foreignSources/{name}/detectors/{detector}: Delete the specified detector from the named foreign source.
/foreignSources/{name}/policies/{policy}: Delete the specified policy from the named foreign source.

SNMP Configuration

You can edit the community string, SNMP version, etc. for an IP address using this interface. If you make a change that would overlap with an existing snmp-config.xml, it will automatically create groups of <definition /> entries as necessary.

GETs (Reading Data)

/snmpConfig/{ipAddress}: Get the SNMP configuration for a given IP address.

PUTs (Modifying Data)

/snmpConfig/{ipAddress}: Add or update the SNMP configuration for a given IP address.

Maps

The SVG maps use ReST to populate their data. This is the interface for doing that.

GETs (Reading Data)

/maps: Get the list of maps.
/maps/{id}: Get the map with the given ID.
/maps/{id}/mapElements: Get the elements (nodes, links, etc.) for the map with the given ID.

POSTs (Adding Data)

/maps: Add a map.

PUTs (Modifying Data)

/maps/{id}: Update the properties of the map with the given ID.

DELETEs (Removing Data)

/maps/{id}: Delete the map with the given ID.

Users

Since users are not currently stored in the database, the ReST interface for them is not as full-fledged as that of nodes, etc. (You cannot use hibernate criteria for filtering, for example.)

GETs (Reading Data)

/users: Get a list of users.
/users/{username}: Get a specific user, by username.

POSTs (Adding Data)

/users: Add a user.

Groups

(New in OpenNMS 1.9.94.)

Like users, groups have a simplified interface as well.

GETs (Reading Data)

/groups: Get a list of groups.
/groups/{groupname}: Get a specific group, by group name.
/groups/{groupname}/users: Get the users for a group, by group name.

POSTs (Adding Data)

/groups: Add a new group.

PUTs (Modifying Data)

/groups/{groupname}/users/{username}: Add a user to the group, by group name and username.

DELETEs (Removing Data)

/groups/{groupname}: Delete a group.
/groups/{groupname}/users/{username}: Remove a user from the group.

Alarm Statistics

(New in OpenNMS 1.9.94.)

It is possible to get some basic statistics on alarms, including the number of acknowledged alarms, total alarms, and the newest and oldest of acknowledged and unacknowledged alarms.

GETs (Reading Data)

/stats/alarms: Returns statistics related to alarms. Accepts the same Hibernate parameters that you can pass to the /alarms ReST service.
/stats/alarms/by-severity: Returns the statistics related to alarms, one per severity. You can optionally pass a list of severities to the "severities" query parameter to limit it to the specified severities. (eg, GET /opennms/rest/stats/alarms/by-severity?severities=MAJOR,CRITICAL).

provision.pl examples and notes

One way to test out the new REST interface is to use provision.pl. If you run it you'll get a summary of the output, but it's not totally obvious how it all works.

Here is an example of adding a new node using the REST interface:

# add a new foreign source called ubr
/usr/share/opennms/bin/provision.pl requisition add ubr
/usr/share/opennms/bin/provision.pl node add ubr 10341111 clownbox
/usr/share/opennms/bin/provision.pl node set ubr 10341111 city clownville
/usr/share/opennms/bin/provision.pl node set ubr 10341111 building clown-town-hall
/usr/share/opennms/bin/provision.pl node set ubr 10341111 parent-foreign-id 1122114
/usr/share/opennms/bin/provision.pl interface add ubr 10341111 10.1.3.4
# this is like a commit.  No changes will take effect until you import a foreign source
/usr/share/opennms/bin/provision.pl requisition import ubr

You will probably need to specify the username/password of an admin. To do this add:

--username=admin --password=clownnms

to the command line.

Debian (Lenny) Notes

For Lenny, you'll need to pull a package out of backports to make everything work right. Read http://backports.org/dokuwiki/doku.php?id=instructions for instructions on adding it to sources.list

# install liburi-perl from backports
sudo apt-get -t lenny-backports install liburi-perl

Get OpenNMS

Get Help

Get Involved

Get to Know Us

Toolbox

From OpenNMS

Contents

ReST URL

Data format

Standard Params

Standard filter examples

Currently Implemented Interfaces

Nodes

GETs (Reading Data)

POSTs (Adding Data)

PUTs (Modifying Data)

DELETEs (Removing Data)

Events

GETs (Reading Data)

PUTs (Modifying Data)

Alarms

GETs (Reading Data)

PUTs (Modifying Data)

Queries

Acknowledgements

GETs (Reading Data)

POSTs (Setting Data)

Notifications

GETs (Reading Data)

Outages

GETs (Reading Data)

Requisitions

GETs (Reading Data)

POSTs (Adding Data)

PUTs (Modifying Data)

DELETEs (Removing Data)

Foreign Sources

GETs (Reading Data)

POSTs (Adding Data)

PUTs (Modifying Data)

DELETEs (Removing Data)

SNMP Configuration

GETs (Reading Data)

PUTs (Modifying Data)

Maps

GETs (Reading Data)

POSTs (Adding Data)

PUTs (Modifying Data)

DELETEs (Removing Data)

Users

GETs (Reading Data)

POSTs (Adding Data)

Groups

GETs (Reading Data)

POSTs (Adding Data)

PUTs (Modifying Data)

DELETEs (Removing Data)

Alarm Statistics

GETs (Reading Data)

provision.pl examples and notes

Debian (Lenny) Notes