6 commentsA 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.
Loading...
Sounds amazing! I’m going to rewrite Icinga Chromed status to use rest API. This is what I was hoping for since begining of Icinga
This is simply great, i really like what i’m seeing about Icinga.
Too bad it’s not really a RESTful interface.
It’s almost pure RPC- or RMI-over-HTTP, it doesn’t honor the semantics of HTTP, it mixes authentication and authorization concerns with resource identifiers (oh right, there really aren’t unique resource identifiers) and some other mishaps.
But enough nagging, thank you for developing a well-defined API! I’m sure it will be very useful and a great feature distinguishing Icinga from vanilla Nagios and some of its other forks.
But please don’t call it REST, just because it’s not SOAP. ;)
Ok, you’re right – we’ll better call it Http-Interface in the future, won’t make it less useful I hope:)
Anyway, have fun with it!
[...] this? Someone trying to defend [...]
Interesting. Sorry, my comparison with Opsview’s API at http://bit.ly/9Q0YR9 only compared to the ‘Icinga API’, because that’s all I could find on your documentation site. I can re-look at the ‘Icinga web rest api’ when you make your documentation final.