Alertra API: Use CURL To Automate Maintenance

Introduction

How long does your maintenance window last? In this tutorial you will learn how to programmatically control Alertra maintenance windows without having to access the Alertra web user interface. This will allow you fine grained control over how long the actual maintenance window lasts so that there are fewer gaps in the coverage of your devices. This tutorial will use Unix shell scripting and the curl command. The Alertra API is implemented as a REST service which uses HTTP URLs, command types and data exchange mechanisms.

Concept

To access your device's maintenance schedule via the Alertra API we will perform the following steps:

1. Request an API key from support.
2. Get a list of devices.
3. Use the device ID to act on that device.

You only need to get an API key once. Send us an email from your primary Alertra account and we'll send you a key. Since the website doesn't force device names to be unique within your account, you need the device list to determine what the unique device identifier is for the one you want to act upon.

Steps

Source Code

Step 1

In this example I'll show you how to start and stop your device's maintenance from inside a bash shell script. The source file contains the commands to start maintenance, stop maintenance, and get a list of devices, but lets look at the guts of it. The shell script is just a wrapper around the curl program. You probably already have curl installed if you are using a platform based on Linux. The curl command to access the Alertra API and get a list of devices looks like this:

curl -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices

where $APIKEY is the API key we sent you. You might want to pipe that output to a file so you can look through it. The response is a text file in the [json][http://json.org/] format. It can be difficult to read json, and at least within the Unix command line there aren't good ways to handle it that don't involve installing third-party packages. If you'd like a viewer for the data there are several on the web like [this one][http://www.jsoneditoronline.org/].

Step 2

Once you have the API key and the device key, starting maintenance on a device looks like this:

curl -X PUT -d "Duration=02:00" -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices/$DEVICEKEY/start-maintenance

Here we do a PUT instead of a GET. The -d option passes some data to the call, in this case the duration of the maintenance window. Here I've set it to 2 hours, but you can use any value from 01:00 to 72:00. You do have to specify a value. If you want to put a device in indefinite maintenance you'll need to do that manually from the website. This is so if something goes wrong with your maintenance program and the call to stop the maintenance isn't made, then the device will still eventually come out of maintenance and hopefully alert you.

Step 3

We don't have to wait for the maintenance window to expire. Once your internal maintenance process has finished we can tell Alertra to cancel the maintenance window. Another curl PUT command does the trick:

curl -X PUT -H "Alertra-API-Key: $APIKEY" -H "Content-Length: 0" https://api.alertra.com/v1.1/devices/$DEVICEKEY/stop-maintenance

Summary

Using the Alertra API you can easily start and stop maintenance on any of your devices. Doing this as part of your automated maintenance routine allows you to insure that Alertra won't be checking your devices during the maintenance and will resume checking them as soon as the maintenance is over.

Source Code

Listing 1. Bash Shell Script

#!/bin/sh

APIKEY="YOUR ACCOUNT API KEY"

case $1 in
    devices)
        curl -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices
    ;;
    start)
        curl -X PUT -d "Duration=$3" -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices/$2/start-maintenance
    ;;
    stop)
        curl -X PUT -H "Alertra-API-Key: $APIKEY" -H "Content-Length: 0" https://api.alertra.com/v1.1/devices/$2/stop-maintenance
    ;;    
esac