Using the REST API
Introduction
Ask Monitor what it knows about your system in this very moment. Filters are written in a made up query language which let's you retrieve data based on certain columns' values, for example "only show me data belonging to hosts whose name begins with an 'A'".
The major differences from using the regular /api/status/host/a_host calls are:
- You can be very expressive and ask for e.g. "all hosts with a problem state that are not acknowledged and not in downtime" with a single HTTP request. Every filter that you have defined in Monitor is copy & pastable into the HTTP API, via the query GET parameter.
- You can limit the data transfered by:
- defining what columns you would like in the output. If you only need to display a list of problem hosts' names and if they are acknowledged or not, you can limit the result to only include those two columns.
This is done through the columns GET parameter, as in
?columns=name,state
- using the limit and offset variables, as if you are paginating something. Append the GET parameters
?limit=5&offset=3
to any request to see it them action.
- All tables and columns are documented in the KB article Listview filter columns.
Start out by choosing any of the sections on the left, either count or query.
Technical information
Authentication
You send along a pair of regular op5 Monitor user credentials in a basic auth header with every request. View any example and you will understand how to do this.
Requests
In a REST-API, there are a couple of important things that make up for a valid request:
-
The URI, in the following form
- /api/filter/
- /api/filter/query
- /api/filter/count
-
The HTTP method
-
The format, appended to the URI
- ?format=xml
- ?format=json (default, except for requests from a browser)
- ?format=html (default in a browser environment)
Once again, viewing any of the examples helps you get into the REST mindset.
Responses
You need to examine two things in the response: the status code and the body. The status code tells you what Monitor did with your input and the body gives you a detailed response.
Examples of status codes:
- 200: Everything went fine.
- 400: You sent a request Monitor didn't understand. Correct the input and try again.
- 401: Authentication required.
- 403: You're not authorized to do this.
- 404: The URI doesn't exist.
These status codes are general for all web traffic and can be found at the List of HTTP status codes