Difference between revisions of "API"
(→Action list) |
|||
(46 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | 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 | + | '''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. | ||
== Overview == | == Overview == | ||
Line 11: | Line 13: | ||
== Usage == | == Usage == | ||
− | We provide open source (under | + | We provide open source (under MIT License) [https://github.com/LunaNode/lndynamic-api 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. [https://github.com/LunaNode/lndynamic-api Get the libraries here.] |
+ | |||
+ | Third party libraries are also available: | ||
+ | |||
+ | * 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. | ||
+ | * 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 89: | Line 98: | ||
=== Technical details === | === 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 [ | + | A request can be made given an API ID, API key, category, action, and parameters. The steps are described below. See the code of [https://github.com/LunaNode/lndynamic-api 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. | * Create request array by taking parameters and adding "api_id" => API ID and "api_partialkey" => first 64 characters of API key. | ||
Line 105: | Line 114: | ||
=== Legacy API === | === 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 | + | 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): | 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): | ||
− | <nowiki>https://dynamic.lunanode.com/api | + | <nowiki>https://dynamic.lunanode.com/api?api_id=YOUR_API_ID&api_key=YOUR_API_KEY&category=vm&action=list |
− | https://dynamic.lunanode.com/api | + | https://dynamic.lunanode.com/api?api_id=YOUR_API_ID&api_key=YOUR_API_KEY&category=vm&action=info&vm_id=FOUND_VM_ID</nowiki> |
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. | 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. | ||
Line 116: | Line 125: | ||
== Action list == | == Action list == | ||
− | This list serves as a | + | This list serves as a reference for available API actions. See [[API Detail]] for additional details for some API operations. |
=== Virtual machine === | === Virtual machine === | ||
Line 138: | Line 147: | ||
|vm | |vm | ||
|reboot | |reboot | ||
+ | |vm_id | ||
+ | |None | ||
+ | |- | ||
+ | |vm | ||
+ | |diskswap | ||
|vm_id | |vm_id | ||
|None | |None | ||
Line 174: | Line 188: | ||
|floatingip-add | |floatingip-add | ||
|vm_id | |vm_id | ||
− | |ip (string unattached floating IP address on your account) | + | |ip (string unattached floating IP address on your account), private_ip (string internal IP on VM) |
|- | |- | ||
|vm | |vm | ||
|floatingip-delete | |floatingip-delete | ||
|vm_id | |vm_id | ||
− | |keep ('yes' to keep floating IP on account; default 'no') | + | |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 | |vm | ||
|create | |create | ||
|hostname, plan_id, image_id | |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 | |vm | ||
|list | |list | ||
|None | |None | ||
+ | |None | ||
+ | |- | ||
+ | |vm | ||
+ | |shelve | ||
+ | |vm_id | ||
+ | |None | ||
+ | |- | ||
+ | |vm | ||
+ | |unshelve | ||
+ | |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, | + | 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 211: | Line 325: | ||
|dns | |dns | ||
|set | |set | ||
− | | | + | |ip, hostname |
|None | |None | ||
|- | |- | ||
Line 281: | Line 395: | ||
|delete | |delete | ||
|image_id | |image_id | ||
− | | | + | |None |
|- | |- | ||
|image | |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 | |None | ||
|} | |} | ||
+ | |||
+ | image.fetch fetches an image from an external source. image.retrieve sends the contents of an existing image as the response body. | ||
=== Volume === | === Volume === | ||
Line 304: | Line 440: | ||
|volume | |volume | ||
|create | |create | ||
− | |region, label (e.g. | + | |region, label (e.g. 'myvolume'), size (in GB) |
− | | | + | |image, snapshot_id |
|- | |- | ||
|volume | |volume | ||
Line 314: | Line 450: | ||
|volume | |volume | ||
|attach | |attach | ||
− | |region, volume_id, vm_id, target (e.g. auto or /dev/vdc) | + | |region, volume_id, vm_id, target (e.g. 'auto' or '/dev/vdc') |
|None | |None | ||
|- | |- | ||
Line 325: | 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 | ||
+ | |} | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! Category | ||
+ | ! Action | ||
+ | ! Required parameters | ||
+ | ! Optional parameters | ||
+ | |- | ||
+ | |floating | ||
+ | |list | ||
+ | |None | ||
+ | |None | ||
+ | |- | ||
+ | |floating | ||
+ | |add | ||
+ | |region | ||
+ | |None | ||
+ | |- | ||
+ | |floating | ||
+ | |delete | ||
+ | |region, ip | ||
+ | |None | ||
+ | |} | ||
+ | |||
+ | === Virtual Network === | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! 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 === | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! 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 | |None | ||
|} | |} | ||
Line 406: | Line 666: | ||
|} | |} | ||
− | === Security groups | + | === Security groups === |
{| class="wikitable" | {| class="wikitable" | ||
Line 418: | 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 | ||
|} | |} | ||
Line 438: | Line 757: | ||
|credit | |credit | ||
|None | |None | ||
+ | |None | ||
+ | |} | ||
+ | |||
+ | === E-mail === | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! 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 | |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.
Contents
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 |
Category | Action | Required parameters | Optional parameters |
---|---|---|---|
usage | None | None | |
domain-list | None | None | |
domain-add | name | None | |
domain-remove | domain_id | None | |
domain-dkim-set | domain_id, selector, private_key | None | |
domain-dkim-unset | domain_id | None | |
user-list | domain_id | None | |
user-add | domain_id, username, password | None | |
user-set-password | domain_id, user_id, password | None | |
user-remove | domain_id, user_id | None | |
alias-list | domain_id | None | |
alias-add | domain_id, name, target | None | |
alias-remove | domain_id, alias_id | None |