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 Horizon.
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 enables Horizon to create REST calls using either XML or JSON. By default, it returns a request to the API as XML data, delivered without namespaces.
| If a namespace is added manually (for example, to use an XML tool like xmllint to validate against the XSD), it won’t be preserved when OpenNMS updates the file that contains that namespace. |
To receive JSON-encoded responses, you must send the Accept: application/json header with the request.
Standard parameters
The following are standard parameters available on most resources:
| Parameter | Description |
|---|---|
|
An integer that limits the number of results returned. This is particularly useful for events and notifications, where sending an accidental call with no limit could result in thousands of results being returned. Such a load could negatively affect the client or the server. + If set to 0, no limit is applied. |
|
An integer representing the numeric offset from which results should start being returned from the total set of results.
For example, if there are 100 result entries total, the |
Filtering: You can specify all properties of the entity being accessed as parameters in either the URL (for GET) or the form value (for PUT and POST).
If the properties are specified as parameters, their values will be used to add filters to the result set.
By default, the operation is equality, unless the |
|
|
Checks for equality. |
|
Checks for non-equality. |
|
Case-insensitive wildcarding ( |
|
Case-sensitive wildcarding ( |
|
Greater than |
|
Less than |
|
Greater than or equal to |
|
Less than or equal to |
Ordering: Define the |
|
|
Defines the parameter by which to sort the results of a request (for example, the ID). |
|
Defines the method used to sort request results (either ascending or descending). |
If null is passed as the value for a property, then the obvious operation will occur.
In other words, the comparator will be ignored for that property.
notnull is handled similarly when passed as a property variable.
Standard filter examples
Using /events as a base, the following table shows examples of REST calls with defined filters:
| Resource | Description |
|---|---|
|
Returns the first 10 events with the rtc subscribe UEI. 10 is the default limit for events. |
|
Returns all rtc subscribe events. This could potentially return quite a few results, and may impact performance. |
|
Returns the first 10 events with an |
|
Returns the first 10 events that have a non-null |
|
Returns the first 20 events that have a non-null |
|
Returns the first 20 events that were acknowledged after July 28, 2008 at 4:41 a.m. (12:00), and that have an `ID` greater than 100. + Note that the same comparator applies to both property comparisons. You must also URL encode the plus sign (``) when using GET. |
|
Returns the 10 latest events inserted. |
|
Returns the first 10 events associated with a node in the |
HTTP return codes
The following apply to OpenNMS Horizon versions 18.0+:
-
DELETE requests return 202 (ACCEPTED) if they are performed asynchronously. Otherwise, they return 204 (NO_CONTENT) on success.
-
All PUT requests return 204 (NO_CONTENT) on success.
-
All POST requests that can either add or update an entity return 204 (NO_CONTENT) on success.
-
All POST requests associated with resource addition return 201 (CREATED) on success.
-
All POST requests where it is required to return an object return 200 (OK).
-
All requests except GET for the requisitions endpoint and the foreign sources definitions endpoint return 202 (ACCEPTED). This is because the requests are performed asynchronously. Because of that, 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, NOT_MODIFIED is returned. NO_CONTENT will be returned only on a successful 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, it returns 404. 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 or DAO Layer when processing any HTTP request, 500 (INTERNAL_SERVER_ERROR) is returned.
-
Any problem related to incoming parameters (for example, validations) generates 400 (BAD_REQUEST).
Identifying resources
Some endpoints deal in resources, which are identified by resource IDs. Since every resource is ultimately parented under a node, identifying the parent node is the first step in constructing a resource ID. Two styles are available for identifying the node in a resource ID:
| Style | Description |
|---|---|
Example |
|
Identifies a node by its database ID, which is always an integer. |
|
|
Identifies a node by its |
The node identifier is followed by a period, then a resource-type name and an instance name. The instance name’s characteristics may vary from one resource-type to the next. A few examples:
| Value | Description |
|---|---|
|
Node-level (scalar) performance data for the node in question. This type is the only one where the instance identifier is empty. |
|
A layer 2 interface as represented by a row in the SNMP |
|
The root filesystem of a node running the Net-SNMP management agent. |
Putting these two parts together, here are some examples of well-formed resource IDs:
-
node[1].nodeSnmp[] -
node[42].interfaceSnmp[eth0-04013f75f101] -
node[Servers:115da833-0957-4471-b496-a731928c27dd].dskIndex[_root_fs]
REST API Explorer
You can view endpoints and API reference documentation directly in the new UI without needing any additional software installed.
The Open API documentation provides information on the available operations and their parameters, and also lets you try some of the operations in your current environment.
To access it, navigate to the new UI and select "Endpoints".
You will then see the REST API Explorer.
The left pane displays all the possible endpoints that you can view and try out.
The right pane allows you to add input parameters (if needed) and click "Try" to send the REST request and display the results.
This screenshot displays an example of sending a REST API request to get all current alarms in the system.
The response status and response time are displayed and you can use the tabs to view the JSON response, response headers, as well as a listing of the corresponding curl command.
Most POST and PUT commands require additional JSON request data; the API Explorer will generally display the schema and some sample JSON for the particular request.
