Difference between revisions of "API"

From Luna Node
Jump to: navigation, search
(Virtual machine)
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
'''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 [https://dynamic.lunanode.com/panel/api API tab] to manage your API keys.
 
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 [https://dynamic.lunanode.com/panel/api API tab] to manage your API keys.
  
Line 17: Line 19:
 
* Golang: a [https://github.com/LunaNode/lobster/tree/master/vmi/lunanode Golang client API] is available as part of the Lobster project.
 
* Golang: a [https://github.com/LunaNode/lobster/tree/master/vmi/lunanode Golang client API] is available as part of the Lobster project.
 
* C#: [https://github.com/rickparrish/lndapi rickparrish/lndapi] is a C# API wrapper.
 
* C#: [https://github.com/rickparrish/lndapi rickparrish/lndapi] is a C# API wrapper.
 +
* PHP: [https://github.com/sdavis1902/lunanode-api-php sdavis1902/lunanode-api-php]
 +
* Ruby: [https://github.com/nomoon/lunanode nomoon/lunanode] Ruby Gem
  
 
If you are using another programming language, you can view the API call [[API#Technical_details|technical details]] below. You may also find it easier to implement the [[API#Legacy_API|Legacy API]].
 
If you are using another programming language, you can view the API call [[API#Technical_details|technical details]] below. You may also find it easier to implement the [[API#Legacy_API|Legacy API]].
Line 204: Line 208:
 
|ip-delete
 
|ip-delete
 
|vm_id, ip
 
|vm_id, ip
 +
|None
 +
|-
 +
|vm
 +
|securitygroup-add
 +
|vm_id, group_id
 +
|None
 +
|-
 +
|vm
 +
|securitygroup-remove
 +
|vm_id, group_id
 
|None
 
|None
 
|-
 
|-
Line 209: Line 223:
 
|create
 
|create
 
|hostname, plan_id, image_id
 
|hostname, plan_id, image_id
|prefer ('distinct' or 'same'), region (default 'toronto'), ip (a floating IP on your account), net_id, securitygroups, scripts, volume_id, volume_virtio, key_id, set_password
+
|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
 
|vm
Line 229: Line 243:
 
|unshelve
 
|unshelve
 
|vm_id
 
|vm_id
 +
|None
 +
|-
 +
|vm
 +
|rename
 +
|vm_id, hostname
 
|None
 
|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, and 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). 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 [https://dynamic.lunanode.com/panel/key 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).
+
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 [https://dynamic.lunanode.com/panel/key 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 ===
 
=== 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'.
+
API calls relating to DNS are listed below (see next section for Legacy DNS).
 +
 
 +
{| class="wikitable"
 +
! 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'.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 251: Line 325:
 
|dns
 
|dns
 
|set
 
|set
|vm_id, ip, hostname
+
|ip, hostname
 
|None
 
|None
 
|-
 
|-
Line 341: Line 415:
 
|retrieve
 
|retrieve
 
|image_id
 
|image_id
 +
|None
 +
|-
 +
|image
 +
|rename
 +
|image_id, name
 
|None
 
|None
 
|}
 
|}
Line 362: Line 441:
 
|create
 
|create
 
|region, label (e.g. 'myvolume'), size (in GB)
 
|region, label (e.g. 'myvolume'), size (in GB)
|image
+
|image, snapshot_id
 
|-
 
|-
 
|volume
 
|volume
Line 382: Line 461:
 
|info
 
|info
 
|region, volume_id
 
|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
 
|None
 
|}
 
|}
  
For volume creation, if image parameter (which should be an image ID) is not set, then an empty volume will be created.
+
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 ===
 
=== Floating IP ===
Line 557: Line 666:
 
|}
 
|}
  
=== Security groups and startup scripts ===
+
=== Security groups ===
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 569: Line 678:
 
|None
 
|None
 
|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 ===
 +
 +
{| class="wikitable"
 +
! Category
 +
! Action
 +
! Required parameters
 +
! Optional parameters
 
|-
 
|-
 
|script
 
|script
 
|list
 
|list
 
|None
 
|None
 +
|None
 +
|-
 +
|script
 +
|get
 +
|script_id
 +
|None
 +
|-
 +
|script
 +
|create
 +
|name, content
 +
|None
 +
|-
 +
|script
 +
|update
 +
|script_id, name, content
 +
|None
 +
|-
 +
|script
 +
|delete
 +
|script_id
 
|None
 
|None
 
|}
 
|}

Latest revision as of 23:15, 17 December 2018

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:

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