REST API Introduction

Opsview REST API Copied

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. See the official REST API Policy.

Connection Copied

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 Copied

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 32 hexadecimal characters. For example, for JSON, you will get

    {
        "token":"7e0d94fba9244d9bbf8bb656d355436d"
    }
    
  3. For all subsequent requests, add the following headers. Replace the username and tokenstring appropriately:

    X-Opsview-Token: tokenstring
    
  4. 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 Copied

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:

Ensure only the utf-8 charset is provided in the Content-Type header, if a charset is provided.

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 Copied

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 Copied

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 Copied

Requests consist of five parts:

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=PUT), or a header (x-http-method-override: PUT).

Response Copied

Responses consist of two parts:

Errors Copied

If there was an error, a corresponding HTTP 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 field may in some cases only be logged locally and not show up in the response."
}

More detailed error information can normally be found in the log on the orchestrator system at /var/log/opsview/opsview.log.

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 Copied

400: Bad Request Copied

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.

If you have violated a constraint set on a specific field, you could need to modify the characters you are trying to insert. See Interacting with Opsview for more details.

401: Unauthorised Copied

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

404: Not Found Copied

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

Always returning an HTTP status 200 Copied

Opsview’s REST API is implemented with pure REST principles, so the HTTP 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": "ACTUALHTTPSTATUS"
}

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

Logging Copied

All REST failures are logged to /var/log/opsview/opsview.log on the orchestrator system with expanded details.

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.

["Opsview On-premises"] ["API", "Technical Reference"]

Was this topic helpful?