Icinga-Web REST API
In this document we'll describe the Icinga-Web REST API which allows you to request your monitoring information via GET or POST requests (in the future (>1.2) , you will also be able to send commands via PUT).
Why should I use the API?
For most people, the combination Icinga/Icinga-web will fit most needs. You can see your monitoring status, act on problems and extend it to suit your needs (Modules/Cronks).
But sometimes, you have another piece of software that is interested in some monitoring data (for example, Icinga-Chromed-Status:http://www.icinga.org/2010/07/16/icinga-chromed-status-for-google-chromechromium/). You could parse the cgi output of Icinga (I think a lot of programs do that at this time), but that's not really a high performance solution - and certainly no fun for the developer.
The goal of the REST API is to return the data you want (and only the data you want) in a standardized, machine-readable format like JSON or XML.
- Availability of almost all monitoring fields via GET or POST.
- Return data as xml or json
- AND & OR Search filtergroups with unlimited nesting levels (AND(OR(AND()))
- You choose which columns you want returned, not the API (less overhead)
- Support of limit, offset, order, group by
- Return an additional total count field
- Authorization via auth_key in request or cookies
- Respects Icinga-web principals (for example, limit to specific hostgroups)
- Since icinga v1.6: Retrieve detailed SLA information or enhance a request with sla information
In order to use the api, you first have to enable the Auth provider for it. This can be done under
Change "auth_enabled" to 'true' in this section:
Afterwards, clear the cache (icinga-web/bin/clearcache.sh).
Now, in icinga-web, you have to add an user with Api access:
- Create a new user
- Choose auth_key in the Auth_via field
- Insert an API Key to use
- Under principals, add the appkit.api.access principal
That's it, now you can start!
In the next few chapters we'll explain how the API can be accessed
- Easy to use, it's just an URL!
- You always see what parameters have been requested
- If you request it in a browser your API Key could be in the browser history
- In a browser, you cannot add URLs with unlimited size (2,083 Characters for Internet explorer, for example)
- Especially when parameters are escaped, the parameter list lacks a bit of clarity
The structure of the URL
To access, the api, the URL should look as in the following (italics are optional, bold ones are required)
host.com/icinga-web/web/api/ %TARGET% / %COLUMNS% / %FILTER% / %ORDER% / %GROUPING% / %LIMIT% / %COUNTFIELD% / %OUTPUT_TYPE%
Parameters in detail
- TARGET : Which field to request, is a simple string like host
- COLUMNS : A listing of columns to return, must look like this: columns[column1|column2|column3]
- FILTER : Defines which filters to use in the request. Must always be nested in AND or OR groups. The filter itself looks like this:
AND query-> filters[AND(%column%|%operator%|%value%;%column%|%operator%|%value%)]
OR query-> filters[OR(%column%|%operator%|%value%;%column%|%operator%|%value%)]
AND \w OR> filters[AND(%column%|%operator%|%value%;OR(%column%|%operator%|%value%;%column%|%operator%|%value%;)]
> Example: Select all services with smtp in the name, but only if they're ok or unknown
>You always need a nesting level at the beginning, see:
>Correct: filtersAND ( SERVICE_NAME
- ORDER : Defines which field to use for ordering and if ascending or descending ordering should be used.
- GROUPING : Defines a field to group by: groupCOL
- LIMIT : Defines a starting offset and/or a limit: limitSTART;END ( if needed ) ||||||||\
- COUNTFIELD : Adds a total field to the result which counts by this field (in most cases, the id): countColumn=COL
- OUTPUT : At this time either json or xml
Example for GET
Get all Services that are critical or warning, but have an host that is ok. Sort descending by the service state and count the services. Authentification is done via authkey (here APITEST123456).
The request is broken in pieces for better readability,
This would return something like
If you change the xml to json you get the same information (plus additional infos for ExtJS, which you can ignore if you're not using it) in json format:
- Unlimited parameter size, as it's made for big requests
- You're parameters don't appear in the browser history, only the base url
- It's easier to implement in applications (ok, that's my opinion )
- POST will be send via the header, so you can't request it easily from the browser's address field
Parameters in detail
The link is almost the same like the GET Baselink, but with the output type in it:
For example, host.com/icinga-web/web/api/json.
The following parameters are supported:
- 'target' : The search target, like host
- 'columns' : An array of columns
- 'groups' : Group by this field
- 'filters_json' : A json describing how to filter
- 'order_col' : Column to order by
- 'order_dir' : Order direction (asc oder desc)
- 'limit_start' : The offset of the records to start
- 'limit' : Limits the result to x responses
- 'countColumn' : Add a total field with this column
Example for POST
Lets take the example from Example for GET and use a post request this time. I'm going to use curl, so the example can be repeated from the console:
This would return the same result as the GET Request shown before.