A lot of people who want to integrate Icinga in their enviroment ask us if there’s a way of requesting database information over an unified API. This is possible over our ‘Icinga-Web REST Adapter’. It’s been in Icinga-Web for about 2 releases now, but I think it’s now time to make it public (as we don’t plan to make any major changes to the format in the future).

So here some facts about REST API:

  • You have to install Icinga-Web in order to use it, because it’s based on the Icinga-Web authorization system. This has some advantages as you can limit access to, for example, only hosts in a specific host group or to items with a special custom variable.
  • You can create users with an API key that can be sent with requests, thus allowing instant authorization. Requests can also be done via POST and via GET.
  • If you don’t want the API, you can disable the authprovider for it (which is disabled by default)

What can I do with REST API?

  • Request almost all Icinga database fields that are supported by Icinga-API (which covers almost all fields)
  • Filter via nested AND and OR groups  (Condition 1  AND (Condition 2 OR (Condition 3 AND Condition 4))..etc.)
  • Add Order, Limit, Group By
  • Get data via XML or JSON
  • Note:  Sending commands via PUT is a work-in-progress and will probably not be supported in Icinga-Web 1.2.

Through one GET request, you could return all SMTP services that are Critical or Warning, 
but only when their corresponding hosts are reachable. You could, for example tell the API to return the name of the service, its state,  its host name, host status and the hostgroup the host is in, and arrange them in descending order by status number.

More details and a complete documentation about how to use the API can be found in our wiki.

…and what about SOAP ?

We’ve already started a SOAP provider, but it’s yet not functional and won’t be available in Icinga-Web 1.2. We decided to focus on REST API, as this will certainly be used more often at this stage.