Ep 46: Working with the Checkmk REST API

[0:00:00]	Hello, my name is Bastian Kuhn and today, I'm gonna show you a short introduction into the Checkmk REST API..
[0:00:18]	First, I'm gonna show you the Swagger documentation, which you can use to play around a bit and to see all the calls which are possible. And then I'm going to show you where you can find some coding examples how to use the API endpoints.
[0:00:34]	At first, let's look into the Swagger documentation. You can find them on the left side, on the Help part. There's a link for REST API interactive GUI.
[0:00:50]	I can open it in a new window. It just takes a moment to load. Okay. After the page is loaded, you just need to scroll a bit down. And in fact it's quite a bit because here you already can find a lot of documentation. It's basically the syntax and the commands you can use for the replacement of the Livestatus queries commands you can use for the replacement.
[0:01:26]	But of course, there is way more you can do. At some point, you're going to end up with the list of endpoints and here we are. They are separated in different groups.
[0:01:42]	You can go, for example, with the agents part, where you can handle everything related to the agent bakery, including getting agents, bake the agents, sign the agents. You can control the Dynamic Configuration Daemon.
[0:02:02]	You can set Acknowledgments, which we look into later. You can activate changes, you can manage tags. You can set even rules for the Business intelligence. You can handle your groups, like Contact groups, Host groups, Service Groups. You can set Downtimes. We're also going to look into that.
[0:02:26]	You can get all the information from the Event Console. You can manage your Folder structure in the Setup. It means creating folders, get a list of the folders, delete folders. You can do the same for hosts.
[0:02:42]	Also, for that we're going to do a little example. So, you can basically create those delete hosts or change even the attributes. In another group you can create tag groups. Then you can manage your Passwords store. You can create every type of Rules. You can search for Rulesets.
[0:03:09]	Here the Service status part is a replacement for everything you did with Livestatus before. You can manage the Service discovery, which means you can start discovery. In other groups in this time the Service groups, you can create Time periods. And finally, Users. The last one is just the version.
[0:03:34]	The good thing here with the specker is you are already authenticated. So, when I click on one of the endpoints, for example, the version here. I can just try it out.This one has no parameters, and click execute. I see the request was sent. I see the URL to which the request is sent.
[0:04:01]	And finally, I can see the response. The response is always like here, is a JSON object. So, then let's do some examples. First, let's start with Acknowledgment. For that, I need to correct endpoint. This's basically on the beginning. Here you can set acknowledgment for host or for service.
[0:04:34]	Let's start with the service. I'm gonna try out. This time, I have a request body, where I need to fill out the needed information. First, acknowledge_type, service. That's correct. We don't want to have the acknowledgment sticky. Sticky means when the acknowledgment is for warning server or for warning service, it will stay acknowledged if the state changes to critical.
[0:05:07]	We don't want the command for persistent. This means the command stays at the service or server even the problem is gone. You don't want to send notification. But what we need is comment. For this example, we just keep it how it is here. And now we just need to fill in the host and the service description.
[0:05:29]	For that, I go back to Checkmk and look for a problem. I have two of them. Let's see. On pve I have the service Check_MK on failure. Let's what's that. I enter then pve, and here "Check_MK". I execute.
[0:06:03]	I again see the curl request, which I can use on the command line to test it out. Just a little information here, if you do the same on the command line, you won't be authenticated, you need some header information for that. But I show you later how this works. For now we stay with the response. Basically, there is none. But let's see.
[0:06:35]	In Check_MK, there is already my acknowledgment. But no, let's say we want to do downtime. I scroll a bit down to the Downtimes part. Then I'm gonna do a host related one. I'm gonna try it out. Then again, I see the the request body. I need to enter some valid information. That's that. No, let's go back to March.
[0:07:24]	Let's start at 10th and go until next month. The option here are start_, end_ time. If you set the duration, which we don't do now, you're gonna create a flexible downtime. This time let's stay with security updates. It's for host and in this time it's for the pve. We execute.
[0:07:59]	And then we should already have a downtime here. And refresh. And with this icon here, I can see the hosts in downtime. And as a final example, I'm going to show how to get the hosts and change the hosts. I know I'm gonna search for the Hosts part, which is here. And the most simple thing is to just get the list of all hosts.
[0:08:30]	To this endpoint, just try out. I execute. And now the response is a little bit bigger just not too big. I only have two objects. And there's a part value on the bottom. There we have the pve host. And we have, wait for more a bit, the cluster object, and a bit down we have the testsrv.
[0:09:10]	So, that are basically our hosts we can work with. If I directly go to a host, let's use this as an example, let's collapse this and go with Show a host. Can Try it out. And the host_name here. The effective_attributes just basically mean if you want to get all attributes, which the host gets by folders.
[0:09:43]	In my example, they are in the main directory and there's stuff or nothing. So, I can save that, just execute it. And now I just have this single object. One little part here is now important. In the response headers, you're also going to find this etag. If we later want.
[0:10:17]	If you later want to change this object, we need to make sure to have the latest etag. So, basically we prevent with this feature that we change within the API, a host which was changed in between from another system. So, imagine you would load the host information, you want to change the host information, and then store it back. But in between this information is changed so the etag will change and you wouldn't be able to update the system then.
[0:10:51]	So, we just copy it for now And then finally, we're gonna add a label to the system For that, we need the update host. It's like here it's the put one. I'm gonna try out. We need to enter the etag header here.
[0:11:22]	We need to enter the host_name. And here you already see a little example how to add new attributes there's this part here. how to update existing attributes, so basically how to change them, and how to remove them. We want to add new ones, so basically I gonna remove this both from the examples. And since we have Json here, you need to remove the comma here as well.
[0:11:58]	It's not like in Python. And we wanted to create the label, so for that would be that we can see how labels look. So, let's go back to the response here. And sadly, if we scroll down in the attributes, we just have a tag but not yet the label.
[0:12:26]	So, to show you how to find out how they look, I'm gonna just add a label to one of the hosts. Let's use this one. Let's go with server: yes. I activate the changes. Then I vary the host.
[0:13:07]	And now we can see in attributes we have a key labels. And there we have also a label. I copy it, paste it in here. I remove the IP address part because I don't need it, I just want to set the label. And testlabel: yes. Execute. Sorry, I need to remove the comma here. Execute.
[0:14:00]	And we see a 200 response. If we look then on the system, we see the label. Another nice way to see these labels is actually also possible in the overview. If I go back to the folder with the Display option, I can, say, Show explicit host labels. And now I can already see it here.
[0:14:32]	If you now want to build your own scripts, I'm going to show you another documentation. It's also with Help. And it's the REST API documentation. Also, this documentation needs a moment to load On the left side then you find some examples. As I showed before, Acknowledgment and Downtimes. Let's use Acknowledgment as an example.
[0:15:08]	You now have the full documentation about the terms. And the best thing here on the right side, you got the examples. This is the normal Payload but you can see a Python example for the whole thing. Another Python example with urllib.
[0:15:32]	On the right side, you can see the Payload You can see a request example with Python. You can see urllib example with Python. And for example, if you want to work on the command line, there's even a curl example with a back script. The final thing we need to talk about is the authentication. It's really simple. It's either a user with a password automation secret.
[0:16:04]	As you can see in the example here,for the authentication just this header is needed. and the username and the password is set here. This users here are nothing else than the ones you can find in Setup, Users. And you can either use the automation, with automation secret or a normal user with a normal password here.
[0:16:32]	I hope this video gave you a short introduction into the Checkmk REST API. Don't forget to subscribe and see you next time.