Backups Added to API Alpha

, by

As development of the new API progresses in tandem with our work on the new manager, we wanted to introduce functionality that our Linode manager has but our current API does not. Backups seemed to be the logical choice, and we’re pleased to announce that its initial integration - enabling, restoring from backups, and snapshots - is now live and available for alpha consumption.

Adding backups in the current manager is as easy as clicking a button. While it seems simple on the surface, quite a few things happen behind the scenes to get it all to work. In this update, we worked closely with our Hardware and Backups teams to get the same functionality and hardware available in our Alpha environment. We’ll be enhancing backups even more, so stay tuned. Hitting the endpoints for Backups is pretty self-explanatory, with one or two small twists and turns. Let’s talk about them now and, while we do, remember that our documentation provides greater detail on Backups and the rest of our burgeoning API.

Enabling Backups

Enabling backups is as easy as a POST method to the specific Linode’s backups “enable” endpoint:

#!/bin/bash
token="a valid oauth token"
linode=$(curl -H "Content-Type: application/json" \
    -H "Authorization: token $token" \
    -X POST https://api.alpha.linode.com/v4/linodes/linode_123/backups/enable)

When you enable backups, a day and window will be chosen for you based on best availability. You can edit the day and window parameters to suit your needs if required, detailed below:

Scheduling

One of the complexities we encountered in bringing Backups into the API was how to handle backup windows - the time slots in which your backups will occur. In our current Manager web interface, you choose a window from a collection of two-hour blocks using the 24-hour clock, from 0000-0200 (midnight to 2AM or, more specifically, 1:59AM) to 2200-2400 (10:00PM to 11:59PM). We admit this is rather confusing, and especially so for us as developers when trying to figure out an easy way to represent this in API calls. We also wanted to be consistent when coupled with scheduling of the backup day. If you wanted to pass “Tuesday” as your scheduled day, we didn’t want you to have to memorize an integer-based index or repeatedly reference our docs because you keep forgetting all the time (though we worked really hard on the docs, so show us some love and check ‘em out).

Our solution was to create an enumeration to simplify the representation of the 24-hour cycle. Instead of trying to pass “0000-0200” in the API, Backup windows are prefixed with the letter “W” followed by an integer representing the start hour of the window you want. So, if you wanted your backups to fall within the 8-10PM EST window on Tuesdays, you would do something like the following:

#!/bin/bash
token="a valid oauth token"
linode=$(curl -H "Content-Type: application/json" \
    -H "Authorization: token $token" \
    -X PUT -d '{
        "backups": {
            "schedule": {
                "day": "Tuesday",
                "window": "W20"
            }
        }
    }' \
    https://api.alpha.linode.com/v4/linodes/linode_123)

Restoring from Backup

You can also restore from a backup by passing the Linode’s ID to the restore endpoint:

#!/bin/bash
token="a valid oauth token"
linode=$(curl -H "Content-Type: application/json" \
    -H "Authorization: token $TOKEN" \
    -X POST -d '{
        "linode": "linode_234"
    }' \
    https://api.alpha.linode.com/v4/linodes/$linode_id/backups/$backup_id/restore)

Spoiler Alert: In the very near future you will be able to use a backup to create a new Linode. Stay tuned for that implementation.

Snapshots

In our first alpha development cycle for Backups, POSTing to a /backups/snapshot endpoint seemed to be the most appropriate place to start the manual backup process. But, we recognized an interesting line being drawn between being RESTful or being more user-friendly, and in this particular case we aired on the side of being more RESTful. To that end, creating a snapshot is done by executing a POST to a specific Linode’s backup endpoint:

#!/bin/bash
token="a valid oauth token"
linode=$(curl -H "Content-Type: application/json" \
    -H "Authorization: token $token" \
    -X POST https://api.alpha.linode.com/v4/linodes/linode_123/backups)

We still have more Backups-related work to do, but we are proud to see this work bringing our API closer to a complete solution for managing your Linodes and other features of our service.

As always, we welcome feedback on these features and others at our documentation github or in the #linode-next channel of OFTC.