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 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] 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". Figure 1. Endpoints menu You will then see the REST API Explorer. Figure 2. OpenNMS 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. Figure 3. Sending REST Request in API Explorer CORS Support Expose ReST services via OSGi