Difference between revisions of "API Detail"

Revision as of 04:24, 23 May 2015

This page includes details about the available API actions. See [API] to get started.

Each action has a category and an action identifier, and can also accept some parameters. Below, whenever single quotes are used (e.g. 'example'), you should not include the quotes in the actual API call.

Virtual Machine

Virtual machine actions have the "vm" category, and allow you to provision and manage virtual machine instances.

Basic Operations

Actions

• start: boot the VM
• stop: shutoff the VM
• reboot: soft reboot the VM
• info: show VM details
• delete: remove VM
• rescue: boot VM to initial OS
• vnc: get VNC URL

Parameters

All basic operations take a single vm_id parameter.

Examples

api.request('vm', 'start', {'vm_id': 55}) # boot VM with id=55
print api.request('vm', 'vnc', {'vm_id': 56})['vnc_url'] # print VNC URL for this VM
print api.request('vm', 'info', {'vm_id': 56})['info']['primaryip'] # print VM id=56 primary IP

Create

• Action identifier: create
• Required parameters:
  • hostname: name for the VM, like "myvm.example.com" or just "myvm"
  • plan_id: ID number of the plan to use (see plan/list action)
  • image_id/volume_id: ID number of image or volume to boot VM from (see image/list and volume/list actions)
• Optional parameters:
  • region: 'toronto' or 'montreal'
  • key_id: ID of an SSH key
  • prefer: either 'distinct' or 'same', to indicate whether we should try to provision VM on the same host node or a different host node
  • net_id: ID number of a virtual network
  • ip: floating IP address already on your account to use to provision the VM (e.g. 38.110.116.1)
  • securitygroups: comma-separated list of security group IDs to apply on this VM
  • scripts: comma-separated list of startup script IDs to apply on this VM
  • set_password: if this key is set, the panel will send a cloud-config startup script to try and set a password for the image's administrative user; the password will be available from info under login_details

Examples

api.request('vm', 'create', {'hostname': 'myvm', 'plan_id': 1, 'image_id': 26}) # create a new 512 MB instance with Ubuntu 14.04 64-bit template image
api.request('vm', 'create', {'hostname': 'myvm', 'plan_id': 1, 'volume_id': 311, 'scripts': '99,100'}) # also use some security groups and boot from a volume

List

• Action identifier: list

Reimage

• Action identifier: reimage
• Parameters:
  • vm_id
  • image_id: ID of image to reinstall VM with

Floating IP management

Use action identifiers 'floatingip-add' and 'floatingip-delete'. The vm_id parameter must be set. To add, can supply optional ip parameter, otherwise a random IP address will be chosen from the available pool. To remove, you can supply 'keep' parameter (either 'yes' or 'no') to indicate whether the floating IP should be kept on your account.

# pick first VM on account and de-associate its floating IP, keep the IP on account
vm_id = api.request('vm', 'list')['vms'][0]['vm_id']
api.request('vm', 'floatingip-add', {'vm_id': vm_id, 'keep': 'yes'})
<nowiki>