Checkmk Conference #6: Welcome to the API world!

When we launch Checkmk 2.0, it will also herald the end of the current Web-API. With the new version we will be introducing our new REST-API, which should make Checkmk’s day-to-day operations easier – as Christoph Rauch explained in his lecture at the Checkmk Conference #6. However the current Web-API will not disappear immediately with 2.0, but will continue to be supported until Checkmk 1.8.

In the long term we want to use the new REST-API to cover all of the functions that are currently available in Checkmk – be it via the GUI or the command line. We are pursuing the goal of making the new API as simple as possible for the user. This means that even less-experienced users can retrieve their values from the API, for example through easy-to-understand error messages, complete documentation of the API, and an API whose behaviour is easy to understand.

With the API we also want to make automation much easier. According to Christoph, this includes perfect documentation – which should also always be up to date. To ensure this, we will automatically-generate the documentation and specifications directly from the source code. We also attach great importance to the backward compatibility of the new API.

Christoph also emphasised that the new API complies with current standards. This has the advantage that the user can fall back on existing software if he wants to program or use his own API client. JSON has established itself as the format for data transport. We also use the current OpenAPI Specification, OpenAPI 3.0 (OAS 3.0), to describe our API, as Christoph further explained. The API is also based on HTTP/1.1. It should also confirm to the third level of the Richardson Maturity Model. This allows, for example, links in the API responses containing further actions to be sent.

With Checkmk 2.0, the Agent Bakery, the BI, likewise the configuration of folders, hosts, services and groups, as well as the rule sets, are planned to be implemented in the new API. We will deliver everything else over time.

In a demonstration Christoph also showed the automatically-generated documentation with the new API, and how the configuration of new hosts works with the new API. The documentation provides concrete examples that should make it easier for the user to carry out the individual steps of a configuration.

Coming soon – the new Check-API

The new REST API is however not the only innovation that we are making on the Checkmk foundations. Developer Moritz Kiemer is taking care of the new Check-API, for example. Although there are now almost 2,000 official plug-ins for Checkmk, the previous Check-API dates from a time when there were significantly fewer extensions. Nor has the Check-API changed over the years. Therefore we decided that it was now urgently necessary to do an overhaul for that. The aim is to treat the check plug-ins as modules in the future that are imported from a versioned, clearly-defined API.

Moritz has already presented how this new arrangement should look at the last conference. For Checkmk 2.0, the transformation of the plug-ins to Python modules, the auto-migration of most existing plug-ins, and a complete change from Python 2 to Python 3 should be on the agenda.

This year Moritz in his lecture presented the principles of the new Check-API. These include the establishment of conventions and consistency – especially with regard to the naming, which in turn should not only be consistent but also explanatory. Another point of the new API is that different things that perform the same function should look the same. There are currently different procedures in Checkmk that lead to the same result. This has the disadvantage that there is no generally-applicable best practice for such cases, and it can be confusing to look at the corresponding code. Moritz promised that this will now change with the new Check-API.

Avoiding unnecessary options

Another goal for the new Check-API is that implied functions work as originally intended by the developer. This also includes reducing unnecessary options. So you should no longer need two different procedures to perform exactly the same function. This means that checks from 2.0 no longer act either as a function, or as a generator, but instead only as a generator, as Moritz explained.

Another advantage of the new Check API is that it makes programming errors visible at an earlier stage, and not first when they are running. The insertion of checks in Python modules should simplify testing and enable them to be carried out independently.

All in all, the new API helps to simplify check development. At the same time, as little as possible will change for the users, since an auto-migration does most of the work. According to Moritz, this only failed in 63 of the 1,920 check plug-ins, which in turn means that it worked for over 96 percent (and these 63 check plug-ins were rather complex). In Werk #10601 Moritz has created a list of causes that can cause problems with the auto-migration of self-written plug-ins.

We plan to migrate the remaining checks over the next few weeks, following which we want to share our findings with you, and consider options for how we can assist our users during the migration.

In our next post you will receive all the news about our new support diagnostics, and what options Checkmk 2.0 has in store for you to test new functions and releases in advance.