API

For the latest API documentation, refer to https://www.lunanode.com/api/overview

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 MIT License) 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. Get the libraries here.

Third party libraries are also available:

• Golang: a Golang client API is available as part of the Lobster project.
• C#: rickparrish/lndapi is a C# API wrapper.
• PHP: sdavis1902/lunanode-api-php
• Ruby: nomoon/lunanode Ruby Gem

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

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?api_id=YOUR_API_ID&api_key=YOUR_API_KEY&category=vm&action=list
https://dynamic.lunanode.com/api?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

This list serves as a reference for available API actions. See API Detail for additional details for some API operations.

Virtual machine

Category	Action	Required parameters	Optional parameters
vm	start	vm_id	None
vm	stop	vm_id	None
vm	reboot	vm_id	None
vm	diskswap	vm_id	None
vm	info	vm_id	None
vm	delete	vm_id	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), private_ip (string internal IP on VM)
vm	floatingip-delete	vm_id	ip (string floating IP attached to VM), keep ('yes' to keep floating IP on account; default 'no')
vm	iplist	vm_id	None
vm	ip-add	vm_id	ip (string unallocated IP in virtual network)
vm	ip-delete	vm_id, ip	None
vm	securitygroup-add	vm_id, group_id	None
vm	securitygroup-remove	vm_id, group_id	None
vm	create	hostname, plan_id, image_id	region (default 'toronto'), ip (a floating IP on your account), net_id, securitygroups, scripts, volume_id, volume_virtio, key_id, set_password, affinity_group
vm	snapshot	vm_id, name (e.g. 'mysnapshot')	None
vm	list	None	None
vm	shelve	vm_id	None
vm	unshelve	vm_id	None
vm	rename	vm_id, hostname	None

Note: for create command, net_id is a network ID number, securitygroups is a comma-separated list of security group ID numbers, scripts is a comma-separated list of script ID numbers, volume_id is the ID number of an unattached volume that the new VM should be booted from (if volume_id is set, image_id is not required), and affinity_group is an affinity group UUID. Also, if volume_id is set, then the driver is ide if volume_virtio is not set, or virtio of volume_virtio is set (value of volume_virtio is ignored). Finally, key_id is an SSH keypair ID, and set_password can be set if you want the system to add a startup script to set a randomly generated password (this is ignored if key_id is set; also, the system will set password by default for official templates).

DNS

API calls relating to DNS are listed below (see next section for Legacy DNS).

Category	Action	Required parameters	Optional parameters
dns2	zone-list	None	None
dns2	zone-add	name (e.g. 'example.com'), ttl	None
dns2	zone-remove	zone_id	None
dns2	record-list	zone_id	None
dns2	record-add	zone_id, name, data, ttl, type	policy, weight, region, regiongroup, country, continent, global, latitude, longitude, aux, monitor_id, orig_record_id
dns2	record-remove	zone_id, record_id	None

Here are details for parameters to the record-add action:

• name: e.g. 'blah' or 'blah.example.com.' for 'blah.example.com.'
• data: the record contents, e.g. '1.2.3.4' for an A record or 'other.example.org.' for a CNAME/MX record
• ttl: time-to-live, e.g. 3600
• type: one of 'A', 'AAAA', 'CNAME', 'ALIAS', 'MX', 'NS', 'TXT', 'SPF', 'SRV'
• policy (optional): geo-targeting policy, 'none' for no geo-targeting, 'latlong' to route to record with closest latitude/longitude to the user's location, and 'region' for hierarchical region-based routing
• weight (optional): the record weight (this is used for load balancing or non-round-robin DNS failover)
• region, regiongroup, country, continent, global (optional): parameters for hierarchical region-based routing, see the UI for details (set global to 'no' to disable for global group)
• latitude, longitude (optional): latitude/longitude for 'latlong' policy
• aux (optional): priority for certain record types, such as MX and SRV
• monitor_id (optional): the ID of a monitor check (see monitor.check-list action), this record will be disabled if the check fails
• orig_record_id (optional): update an existing record with the specified ID instead of creating a new record

Legacy DNS

API calls relating to Legacy 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	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 (will show images across all regions by default)
image	delete	image_id	None
image	details	image_id	None
image	replicate	image_id, region	None
image	fetch	region, name, location, format ('iso' or 'qcow2')	virtio
image	retrieve	image_id	None
image	rename	image_id, name	None

image.fetch fetches an image from an external source. image.retrieve sends the contents of an existing image as the response body.

Volume

Category	Action	Required parameters	Optional parameters
volume	list	region	None
volume	create	region, label (e.g. 'myvolume'), size (in GB)	image, snapshot_id
volume	delete	region, volume_id	None
volume	attach	region, volume_id, vm_id, target (e.g. 'auto' or '/dev/vdc')	None
volume	detach	region, volume_id	None
volume	info	region, volume_id	None
volume	extend	region, volume_id, size (in GB)	None
volume	snapshot-create	region, volume_id, label	None
volume	snapshot-delete	region, snapshot_id	None
volume	snapshot-list	region	None
volume	snapshot-replicate	region, snapshot_id, image_name (e.g. 'myimage'), dst_region (e.g. 'toronto')	None
volume	rename	volume_id, name	None

For volume creation, if image parameter (which should be an image ID) and snapshot_id parameter are not set, then an empty volume will be created. If both are set, an error will be returned.

Floating IP

Category	Action	Required parameters	Optional parameters
floating	list	None	None
floating	add	region	None
floating	delete	region, ip	None

Virtual Network

Category	Action	Required parameters	Optional parameters
network	list	None	region
network	create	region, name, subnet (e.g. '192.168.30' for 192.168.30.0/24), dns (e.g. '8.8.8.8,8.8.4.4')	None
network	delete	region, net_id	None

Load Balancer

Category	Action	Required parameters	Optional parameters
lb	list	region	net_id
lb	create	region, net_id, name, method ('ROUND_ROBIN', 'LEAST_CONNECTIONS', or 'SOURCE_IP'), protocol ('HTTP', 'HTTPS', or 'TCP'), connection_limit (-1 for unlimited), port	None
lb	delete	region, lb_id	None
lb	info	region, lb_id	None
lb	member_add	region, lb_id, ip, port	None
lb	member_remove	region, lb_id, member_id (see lb/info output)	None
lb	associate	region, lb_id, ip	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

Security groups

Category	Action	Required parameters	Optional parameters
securitygroup	list	None	None
securitygroup	create	region, name	None
securitygroup	delete	region, group_id	None
securitygroup	rename	region, group_id, name	None
securitygroup	rule-list	region, group_id	None
securitygroup	rule-insert	region, group_id, direction ('ingress' or 'egress'), type (4 or 6), protocol ('*', 'tcp', 'udp', or 'icmp'), remote_type ('cidr' or 'group'), remote_value (CIDR or group ID)	port_min, port_max, label
securitygroup	rule-delete	region, group_id, rule_id	None

Startup scripts

Category	Action	Required parameters	Optional parameters
script	list	None	None
script	get	script_id	None
script	create	name, content	None
script	update	script_id, name, content	None
script	delete	script_id	None

Billing

You can check your credit balance from the API.

Category	Action	Required parameters	Optional parameters
billing	credit	None	None

E-mail

Category	Action	Required parameters	Optional parameters
email	usage	None	None
email	domain-list	None	None
email	domain-add	name	None
email	domain-remove	domain_id	None
email	domain-dkim-set	domain_id, selector, private_key	None
email	domain-dkim-unset	domain_id	None
email	user-list	domain_id	None
email	user-add	domain_id, username, password	None
email	user-set-password	domain_id, user_id, password	None
email	user-remove	domain_id, user_id	None
email	alias-list	domain_id	None
email	alias-add	domain_id, name, target	None
email	alias-remove	domain_id, alias_id	None