
= REST API

A RESTful interface is a web service conforming to the REST architectural style as described in http://oreilly.com/catalog/9780596529260[_RESTful Web Services_].
This section describes the RESTful interface for {page-component-title}.

== 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 {page-component-title} to create REST calls using either XML or JSON.
By default, it returns a request to the API as XML data, delivered without namespaces.

NOTE: 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:

[cols="1,4"]
|===
| Parameter | Description

| limit
| 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.

| offset
| 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 `offset` is `15`, and the `limit` is `10`, then entries 15-24 will be returned.
Used for pagination.

2+| *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 `comparator` parameter is sent.
In that case, `comparator` applies to all comparisons in the filter. +
Specifying multiple properties will result in an implicit `AND` operator between the elements.

| 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 to.

| le
| Less than or equal to.

2+| *Ordering*: Define the `orderBy` and `order` parameters in a request to sort results by a specified parameter.
By default, the results are ordered by ascending.

| orderBy
| Defines the parameter by which to sort the results of a request (for example, the ID).

| order
| 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:

[cols="2,2"]
|===
| Resource  | Description

| /events?eventUei=uei.opennms.org/internal/rtc/subscribe
| Returns the first 10 events with the rtc subscribe UEI.
`10` is the default limit for events.

| /events?eventUei=uei.opennms.org/internal/rtc/subscribe&limit=0
| Returns all rtc subscribe events.
This could potentially return quite a few results, and may impact performance.

| /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 `AckTime` (in other words, those that have been acknowledged).

| /events?eventAckTime=notnull&id=100&comparator=gt&limit=20
| Returns the first 20 events that have a non-null `AckTime` 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 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.

| /events?orderBy=id&order=desc
| Returns the 10 latest events inserted.
ifndef::opennms-prime[]

| /events?location.id=MINION
| Returns the first 10 events associated with a node in the `MINION` location.
endif::opennms-prime[]
|===

== 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:

[cols="2,3,3"]
|===
| 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 an instance name.
The instance name's characteristics may vary from one resource-type to the next.
A few examples:

[cols="1,3"]
|===
| 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 2 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 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*.

.OpenNMS UI sidebar
image::development:rest/api-explorer-navigation.png["OpenNMS navigation sidebar. Endpoints is highlighted.", 240]

You will then see the REST API Explorer.

.OpenNMS REST API Explorer
image::development:rest/rest-api-explorer.png["OpenNMS UI displaying 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.

.Sending a REST request in the API Explorer
image::development:rest/rest-api-explorer-request.png["OpenNMS UI displaying the REST API Explorer. A REST request has been sent, and its results are shown."]
