REST API

A RESTful interface is a web service conforming to the REST architectural style as described in RESTful Web Services. This section describes the RESTful interface for Meridian.

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.

Authentication

Use HTTP basic authentication to provide a valid username and password. By default you will not receive a challenge, so you must configure your REST client library to send basic authentication proactively.

Data Format

Jersey lets REST calls to be made using either XML or JSON. By default, returns a request to the API in XML. XML is delivered without namespaces.

If a namespace is added manually, in order to use a XML tool to validate against the XSD (like xmllint) it won’t be preserved when OpenNMS updates that file. The same applies to comments.

To get JSON-encoded responses one has to send the following header with the request: Accept: application/json.

Standard Parameters

The following are standard parameters available on most resources (noted below):

Table 1. REST standard parameter for resources
Parameter Description

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. For example, 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)

Standard Filter Examples

Take /events as an example.

Resource Description

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

Returns 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

Returns all the rtc subscribe events (potentially quite a few).

/events?id=100&comparator=gt

Returns the first 10 events with an ID greater than 100.

/events?eventAckTime=notnull

Returns 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

Returns 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%2B12:00&id=100&comparator=gt&limit=20

Returns the first 20 events that have were acknowledged after 28th July 2008 at 4:41 a.m. (+12:00), and an ID greater than 100. Note that the same comparator applies to both property comparisons. Also note that you must URL encode the plus sign when using GET.

/events?orderBy=id&order=desc

Returns the 10 latest events inserted (probably, unless you’ve been messing with the IDs).

/events?location.id=MINION

Returns the first 10 events associated with some node in location 'MINION'

HTTP Return Codes

The following apply for OpenNMS Horizon 18 and newer.

  • DELETE requests return a 202 (ACCEPTED) if they are performed asynchronously, otherwise they return a 204 (NO_CONTENT) on success.

  • All the PUT requests return a 204 (NO_CONTENT) on success.

  • All the POST requests that can either add or update an entity return a 204 (NO_CONTENT) on success.

  • All the POST associated to resource addition return a 201 (CREATED) on success.

  • All the POST requests where it is required to return an object return a 200 (OK).

  • All the requests excepts GET for the requisitions end-point and the foreign sources definitions end-point return 202 (ACCEPTED). This is because all the requests are actually executed asynchronously and there is no way to know the status of the execution, or wait until the processing is done.

  • If a resource is not modified during a PUT request, a NOT_MODIFIED will be returned. A NO_CONTENT will be returned only on a success operation.

  • All GET requests return 200 (OK) on success.

  • All GET requests return 404 (NOT_FOUND) when a single resource does not exist, but will return 400 (BAD_REQUEST) if an intermediate resource doesn’t exist. For example, if a specific IP doesn’t exist on a valid node, return 404. But if the IP is valid and the node is not valid, because the node is an intermediate resource, a 400 will be returned.

  • If something not expected is received from the Service/DAO Layer when processing any HTTP request, like an exception, a 500 (INTERNAL_SERVER_ERROR) will be returned.

  • Any problem related to the incoming parameters, like validations, generates a 400 (BAD_REQUEST).

Identifying Resources

Some endpoints deal in resources, which are identified by resource IDs. Since every resource is ultimately parented under some node, identifying the node that contains a resource is the first step in constructing a resource ID. Two styles are available for identifying the node in a resource ID:

Style Description Example

node[ID]

Identifies a node by its database ID, which is always an integer

node[42]

node[FS:FID]

Identifies a node by its foreign-source name and foreign-ID, joined by a single colon

node[Servers:115da833-0957-4471-b496-a731928c27dd]

The node identifier is followed by a period, then a resource-type name and instance name. The instance name’s characteristics may vary from one resource-type to the next. A few examples:

Value Description

nodeSnmp[]

Node-level (scalar) performance data for the node in question. This type is the only one where the instance identifier is empty.

interfaceSnmp[eth0-04013f75f101]

A layer two interface as represented by a row in the SNMP ifTable. The instance identifier is composed of the interface’s ifName and its ifPhysAddress (if it has one).

dskIndex[_root_fs]

The root filesystem of a node running the Net-SNMP management agent.

Putting it all together, here are a few well-formed resource IDs:

  • node[1].nodeSnmp[]

  • node[42].interfaceSnmp[eth0-04013f75f101]

  • node[Servers:115da833-0957-4471-b496-a731928c27dd].dskIndex[_root_fs]