Introduction

Introduction and overview of the Opsview Monitor Rest API

Opsview REST API

Opsview has a REST API for updating the Opsview configuration using web service calls on the Orchestrator server. This uses the same underlying models and procedure as the web interface.

You should use the REST API to update the configuration data in Opsview as object updates are made within transactions (so a failure will rollback other related changes) and there is a lot of validation to ensure that the data is correct.

There is an official REST API Policy.

Connection

Connection to the REST API is via HTTP or HTTPS, based on how you have configured the Opsview web server. We recommend using HTTPS to encrypt the traffic between the client and the Opsview web server.

The API is hosted under the /rest URL. If you want to use a specific domain for the API, such as api.opsview.example.com, this could be achieved by configuring Apache to proxy a different site through to Opsview Web.

Authentication

The Opsview API authentication requires an authentication token. This is more secure than sending a password on every request because, after the initial login, all authentication is handled via a token. The token has an expiry time of 1 hour on it but every successful request will extend the expiry time.

You need to log in to Opsview to receive the authentication token. You then need to pass the authentication token for each request.

The flow is:

  1. POST to /rest/login with a username and password. This can be with request parameters or as the request body in a data format (eg, if content-type is set to application/json and body is set to ”{'username':'admin','password':'initial'}”, then Opsview will use those parameters for login).
  2. The response body will include the token value. This is, by default, returned as a Perl structure but, by changing the accept header, a different format can be returned (eg JSON or YAML). The token is 40 hexadecimal characters. For example, for JSON, you will get
{
    "token":"bdd6ad8e242a993107f13260a7007e38384ce4aa"
}
  1. For all subsequent requests, add the following headers. Replace the username and tokenstring appropriately:
X-Opsview-Username: username
X-Opsview-Token: tokenstring
  1. If there are any errors, an appropriate status code will be set and the body will contain the appropriate data type with
{
    message => "error string"
}

To reduce the possibility of a CSRF attack, the authorisation token is not implemented as a cookie.

Data exchange

You can exchange data between the web service and your script by using either JSON, serialized Perl objects, or XML.

Use Content-Type headers to change the input and output data. Currently tested for:

  • application/json (JSON)
  • text/x-data-dumper (Perl format)
  • text/xml (XML format. More details on XML Serialisation.)

You should always set a Content-Type header and the Accept header should be set to the same value. Alternatively, for GET requests only, it is possible to force a content type using a URL parameter, for example: “content-type=application/json”.

Output as strings

With JSON output, all values are returned as strings. Be aware that in Javascript, if you need to add two strings together numerically, you will need to force a conversion to integers, otherwise a ”+” is considered to be string concatenation. Use the following: ”(value1-0)+(value2-0)”.

Date and time values as epoch seconds

All date and time values are returned as epoch seconds (as a string), which by definition is always UTC.

It is possible to format the date/time value based on the time zone of the Opsview server by using the URL parameter, “format_datetime=1”. This will return a string of the format “YYYY-MM-DD HH:MM:SS”.

Request

Requests consist of five parts:

  • A URL
  • URL parameters
  • A verb (one of PUT, POST, GET, DELETE)
  • Headers, to change behaviour of the input and output data
  • Data, if necessary

If you cannot use a verb, it is possible to use POST and then tunnel the required verb through using a POST parameter (x-tunneled-method).

Response

Responses consist of two parts:

  • A status code
  • Data, if necessary

Always returning a status 200

Opsview's REST API is implemented with pure REST principles, so the status code of the response reflects the error (eg, 401 for authentication denied). However, sometimes you always want a 200 response back, for instance, if you are using JSONP.

If you set a URL parameter of “alwaysReturn200=1”, then the status will always be 200 and there will always be REST data, which will be added into the keyword, “rest”:

{
    "rest": "NORMALRESTDATA",
    "status": "ACTUALSTATUS"
}

If there is no data, then rest will be set to null.

Errors

If there was an error, a corresponding status code will be set. Data will be sent with the format in the form of:

{
    message => "Text explaining the error",
    detail  => "Text with further detail. This may not exist",
}

Note: The content returned may be in a different format than the one requested. For instance, invalid data structures (400 bad request) could return content-type text.

Common errors

400: Bad Request

This can mean that the input parameters cannot be parsed. There should be more information in the content.

If the contents shows something like:

Content-Type application/json had a problem with your request.
***ERROR***
malformed JSON string, neither array, object, number, string or atom, at character offset 180 (before "],\n      "all_servi..."),
 <$fh> line 21.

Then this means there is some invalid JSON data. JSON input is set to “relaxed”, so additional commas at end of lists are valid.

401: Unauthorised###

This means you have not authenticated to the REST API, ie. not logged in.

404: Not Found###

You will get this error if you try to access a URL that does not exist.

Logging

All REST failures are logged to syslog.

This will show a line like:

REST response (ERROR=403): GET /rest/config/monitoringcluster?cols=-monitors Data:{ message => "Access denied" }

If you want to log all REST requests and responses, uncomment this in /opt/opsview/webapp/etc/Log4perl.conf:

log4perl.logger.Opsview.Web.ControllerBase.REST=DEBUG

It can take up to 30 seconds after the file is saved, to start logging. Note that logging may increase the response times of Opsview Web.