API

From Luna Node
Revision as of 01:07, 14 December 2014 by Favyen Bastani (Talk | contribs)

Jump to: navigation, search

The Luna Node Dynamic API enables you to write software to automate VM management. This page details how the API can be accessed. Visit the API tab to manage your API keys.

Overview

Each API token consists of an API ID and an API key. Both are needed for authentication of all API commands.

API actions consist of a category label, action label, and a set of parameters. For example, to start a VM, the category label is "vm", action label is "start", and a "vm_id" parameter must be set. See the full API action list.

API requests are made over HTTPS. Once the server completes processing of your request, it will return a JSON-encoded response.

Usage

We provide open source (under CC0 1.0) PHP and Python libraries for accessing the Luna Node Dynamic API. These libraries make interaction with the API easier, handling transaction from category, action, and parameters to the HTTPS request, and from the JSON-encoded response to a PHP associative array or Python dictionary. Download the libraries here.

If you are using another programming language, you can view the API call technical details below. You may also find it easier to implement the Legacy API.

Examples

List your virtual machines:

<?php

require_once('lndynamic.php');
$api_id = 'YOUR API ID';
$api_key = 'YOUR API KEY';
$api = new LNDynamic($api_id, $api_key);
print_r($api->request('vm', 'list'));

?>
from lndynamic import LNDynamic
api_id = 'YOUR API ID'
api_key = 'YOUR API KEY'
api = LNDynamic(api_id, api_key)
print api.request('vm', 'list')

Recreate a VM with the same IP:

<?php

require_once('lndynamic.php');
$api_id = 'YOUR API ID';
$api_key = 'YOUR API KEY';
$target_vm_name = 'myvm';
$target_image_name = 'Ubuntu 14.04 64-bit (template)';
$api = new LNDynamic($api_id, $api_key);

// find the target virtual machine ID
$vms = $api->request('vm', 'list');
$target_vm_id = false;

foreach($vms['vms'] as $vm) {
	if(strcasecmp($vm['name'], $target_vm_name) === 0) {
		$target_vm_id = $vm['vm_id'];
		break;
	}
}

//find the target image ID
$images = $api->request('image', 'list');
$target_image_id = false;

foreach($images['images'] as $image) {
	if(strcasecmp($image['name'], $target_image_name) === 0) {
		$target_image_id = $image['image_id'];
		break;
	}
}

if($target_vm_id === false) {
	die('No VM found!');
}

if($target_image_id === false) {
	die('No image found!');
}

// disassociate the IP address
$info = $api->request('vm', 'info', array('vm_id' => $target_vm_id));
if(empty($info['info']['ip'])) {
	die('VM does not have IP!');
}
$api->request('vm', 'floatingip-delete', array('vm_id' => $target_vm_id, 'keep' => 'yes'));
$api->request('vm', 'delete', array('vm_id' => $target_vm_id));
$api->request('vm', 'create', array('hostname' => $info['info']['hostname'], 'plan_id' => $info['extra']['plan_id'], 'image_id' => $target_image_id, 'ip' => $info['info']['ip']));

?>

Technical details

A request can be made given an API ID, API key, category, action, and parameters. The steps are described below. See the code of provided API libraries for more details.

  • Create request array by taking parameters and adding "api_id" => API ID and "api_partialkey" => first 64 characters of API key.
  • JSON-encode the request array to get a raw request message.
  • The nonce is the current UTC time in seconds since epoch (in PHP, $nonce = time();).
  • The handler path is "{category}/{action}/"
  • The target URL is https://dynamic.lunanode.com/api/{handler path}
  • Calculate the signature as SHA512-HMAC("{handler path}|{raw request message}|{nonce}"), using the API key as the HMAC key; here, we are signing the string formed from concatenating handler path, raw request message, and nonce delimited by pipe (|) characters
  • Submit POST request to target URL with these form keys:
    • req: the raw request message
    • signature: the hex-digest output of the SHA512-HMAC
    • nonce: the nonce value
  • The server's response will be a JSON-encoded associative array.

Legacy API

The legacy API uses simple GET and POST requests for each API action. All API actions are submitted via https://dynamic.lunanode.com/api.php

For example, to get the info for a virtual machine with hostname "hostname.example.tld", you can use the following API actions (find the ID for the hostname, then get the info from the ID):

https://dynamic.lunanode.com/api.php?api_id=YOUR_API_ID&api_key=YOUR_API_KEY&category=vm&action=list
https://dynamic.lunanode.com/api.php?api_id=YOUR_API_ID&api_key=YOUR_API_KEY&category=vm&action=info&vm_id=FOUND_VM_ID

The legacy API isn't necessarily less secure than the newer API, as either way all API actions are encrypted under HTTPS; however, the new API does offer greater protection against timing attacks and hides the API key even if an attacker were able to successfully forge an SSL certificate. So, we encourage usage of the new API where it is not inconvenient, but we plan to maintain the legacy API indefinitely.

Action list

Virtual machine

Category Action Required parameters Optional parameters
vm start vm_id None
vm stop vm_id None
vm reboot vm_id None
vm info vm_id None
vm delete vm_id None
vm setpassword vm_id, password None
vm reimage vm_id, image_id None
vm resize vm_id, plan_id None
vm rescue vm_id None
vm vnc vm_id None
vm floatingip-add vm_id ip (string unattached floating IP address on your account)
vm floatingip-delete vm_id keep ('yes' to keep floating IP on account; default 'no')
vm create hostname, plan_id, image_id prefer ('distinct' or 'same'), region (default 'toronto'), ip (a floating IP on your account)
vm list None None

DNS

API calls relating to DNS are listed below. Valid DNS record types are 'A', 'AAAA', 'CNAME', 'HINFO', 'MX', 'NAPTR', 'NS', 'PTR', 'RP', 'SRV', and 'TXT'.

Category Action Required parameters Optional parameters
dns list None None
dns set vm_id, ip, hostname None
dns zone-list None None
dns zone-add origin (e.g., 'example.tld.') ttl
dns zone-remove zone_id None
dns record-list zone_id None
dns record-add zone_id, name (e.g., 'www'), data (e.g., '1.2.3.4'), ttl, type None
dns record-remove record_id None
dns dyn-list None None
dns dyn-add name, ip None
dns dyn-update dyn_id, name, ip None
dns dyn-remove dyn_id None

Image

Category Action Required parameters Optional parameters
image list None region (default 'toronto')
image delete image_id
image create vm_id, name None

Plan and region

Category Action Required parameters Optional parameters
plan list None None
region list None None

Server monitoring

Category Action Required parameters Optional parameters
monitor check-list None None
monitor check-types None None
monitor check-add name, type, fail_count, success_count, check_interval, (also any parameters needed from check-types) None
monitor check-remove check_id None
monitor contact-list None None
monitor contact-add None None
monitor contact-remove type ('email', 'sms_twilio', or 'http'), rel (e-mail address, phone number, or URL) None
monitor alert-list check_id None
monitor alert-add check_id, contact_id None
monitor alert-remove alert_id None