sales@elastichosts.com

API

Our ReSTful HTTP cloud computing API allows users to create drives, upload and download drive images, and create and control virtual servers on our infrastructure. You can download our ready-made command line tools, or make direct calls to the API from your own scripts. Expand all answers

Install our command-line tools

Installing the Tools

We provide ready-made scripts to let you control your cloud computing platform infrastructure without writing any code.

Linux/Unix and Windows Cygwin users should download our simple command line tool, drive upload tool and drive download tool.

Once you have these scripts, in just two commands, you can upload a drive image and boot a server. See below for the full input and output to do exactly this.

 

Worked example – using the tools

Worked example – using the tools

Each command corresponds to a single API HTTP GET or POST, with the URL corresponding to the command-line arguments, and the input and output data exactly as seen on the command line here. 1. Set API end-point for your availability zone Substitute api-lon-b.elastichosts.com if your account is there. Alternatively, you can hard-code the value of EHURI in your local copy of the scripts.
      $ export EHURI=https://api-lon-p.elastichosts.com/
2. Set authentication credentials (from account profile) Omit the secret key if you are running on a very old Unix system that leaks the content of your environment to other users via ps e. You will then be interactively prompted for your secret key by curl. Alternatively, you can hard-code the value of EHAUTH in your local copy of the scripts, but make sure they aren’t world-readable!
      $ export EHAUTH=<user uuid>:<secret API key>
3. Create drive and upload image We use the drive upload tool to automatically upload in gzipped chunks.
      $ elastichosts-upload image.raw
      Created drive 08c92dd5-70a0-4f51-83d2-835919d254df of size 10000000
      Uploading 2 chunks of 5242880 bytes: .. completed
NOTE: for reference, a more basic upload with the raw API would be:
      $ elastichosts -c drives create << EOF | grep drive
      $ > name TestDrive
      $ > size 10000000
      $ > EOF
      $ drive 08c92dd5-70a0-4f51-83d2-835919d254df
      $ elastichosts -f image.raw drives 08c92dd5-70a0-4f51-83d2-835919d254df write
4. Boot a server from the drive Boot a server from the drive, with 2000 core MHz and 1024 MB RAM.
      $ elastichosts -c servers create << EOF
      > name TestServer
      > cpu 2000
      > mem 1024
      > ide:0:0 08c92dd5-70a0-4f51-83d2-835919d254df
      > boot ide:0:0
      > nic:0:model e1000
      > nic:0:dhcp auto
      > smp auto
      > vnc auto
      > password XXXXXXXX
      > EOF
      server 85ef58c8-6f5d-4f7f-8f1c-0c19d45d7c1c
      name TestServer
      cpu 2000
      smp auto
      smp:cores 1
      smp:sockets 1
      mem 1024
      ide:0:0 08c92dd5-70a0-4f51-83d2-835919d254df
      boot ide:0:0
      nic:0:dhcp auto
      nic:0:dhcp:ip 91.203.56.132
      nic:0:model e1000
      rx 0
      tx 0
      vnc auto
      vnc:ip 91.203.56.132
      password XXXXXXXX

Using the cloud computing API

Using the API

The API is implemented in a ReST style, using the URL to specify an object and an action, HTTP GET to read state and HTTP POST to change state. In the description below, API URLs are relative to the stem https://api-lon-p.elastichosts.com/ where api-lon-p refers to the availability zone for our Peer 1 availability zone near London in the UK.

Users, drives and servers are identified by UUIDs, which are assigned by our infrastructure and passed as a string in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX.

Authentication

API calls must use HTTP Basic Authentication, specifying the user’s UUID as the username and their secret API key as the password. Both are available from the user’s account profile.

Data formats

The API can be used in either text/plain(default) or application/json modes. You should specify the type of input data with an HTTP Content-Type: header, and request a type for output with an HTTP Accept: header. text/plain is the default if no headers are set.

The API sends or receives one of three types of data, according to the call:

text/plain application/json
Single object, key value pairs of properties

Multiple lines of text, each containing a key, followed by a space, followed by the value. e.g.:

name TestServer
cpu 4000
mem 2048

Data is accompanied by the HTTP header ‘X-Elastic-Output: properties’

JSON object. e.g.:

{"name":"TestServer", "cpu":4000, "mem":2048}
Multiple objects, list of values

Multiple lines of text, each containing a space separated list of values for the same set of keys. e.g.:

ip 192.168.0.1
ip 192.168.0.2
ip 192.168.0.3

Data is accompanied by the HTTP header ‘X-Elastic-Output: list’

JSON array of objects. e.g.:

 [{"type":"ip", "resource":"192.168.0.1"},
  {"type":"ip", "resource":"192.168.0.2"},
  {"type":"ip", "resource":"192.168.0.3"}]
Multiple objects, key value pairs of properties for each

Multiple lines of text, each containing a key, followed by a space, followed by the value. Blank lines separating objects. e.g.:

name TestServer1
cpu 2000
mem 1024
name TestServer2
cpu 4000
mem 2048

Data is accompanied by the HTTP header ‘X-Elastic-Output: properties list’

JSON array of objects. e.g.:

 [{"name":"TestServer1", "cpu":2000, "mem":1024},
  {"name":"TestServer2", "cpu":4000, "mem":2048}]

 

Errors

Errors are returned with an appropriate HTTP status code, an X-Elastic-Error header specifying the error type, and a text description in the HTTP body. The error types are:

HTTP status code X-Elastic-Error Meaning
200 OK n/a Command succeeded, data returned (possibly 0 length)
204 No Content n/a Command succeeded, no data returned (by definition)
400 Bad Request usage Invalid input data to command
401 Unauthorized auth HTTP Basic Authentication missing or incorrect
402 Payment Required billing Account balance and/or subscriptions do not cover command
404 Not Found missing Command, drive, server or other object not found
405 Method Not Allowed method GET used on command expecting POST
409 Conflict busy Drive, server or other resource is busy
500 Internal Server Error failed Failed command
500 Internal Server Error system System error
507 Insufficient Storage full Drive or other resource is full

 

Drive API

Using the Drive API

List all drives
GET /drives/list
Returns for each drive, a list of
DRIVE

 

Get single drive info
GET /drives/DRIVE/info
Returns KEY VALUE pairs:
name Drive name
drive DRIVE
size size of drive in bytes
status active | inactive
claimed present if drive is in use by a server, values are the server uuids
claim:type optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously
imaging ‘true’ if this is underway, or ‘queued’ if waiting for another imaging operation to complete first. If a drive is imaging, a call to /info/full will show the percentage completed.
[read|write]:[bytes|requests] Cumulative i/o byte/request count for each drive
readers optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
encryption:cipher optional, either ‘none’ or ‘aes-xts-plain’ (the default)
user owner of the drive

 

Get all drives info
GET /drives/info
Returns for each drive, KEY VALUE pairs as drive info

 

Create a drive
POST /drives/create
Expects KEY VALUE pairs:
name Drive name
size size of drive in bytes
claim:type optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously
readers optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
avoid optional, space-separated list of existing drives to ensure this new drive is created on physical different hardware than those existing drives
encryption:cipher optional, either ‘none’ or ‘aes-xts-plain’ (the default)
Returns KEY VALUE pairs as drive info
Notes size is specified in bytes, optionally with a k/M/G/T suffix.

 

Destroy a drive
POST /drives/DRIVE/destroy
Expects Empty POST
Returns HTTP 204 No Content

 

Set extra drive data
POST /drives/DRIVE/set
Expects KEY VALUE pairs:
name Drive name
size size of drive in bytes
claim:type optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously
readers optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
Returns KEY VALUE pairs as drive info
Notes size is specified in bytes, optionally with a k/M/G/T suffix.

 

Image a drive from another drive
POST /drives/DRIVE/image/SOURCE[/CONVERSION]
Expects Empty POST
Returns HTTP 204 No Content
Notes Supports ‘gzip’ or ‘gunzip’ conversions. The actual imaging process is asynchronous, with progress reported via drive info.

 

Read binary data from a drive
GET /drives/DRIVE/read/OFFSET/SIZE
Returns Binary data (Content-Type: application/octet-stream)
Notes OFFSET and SIZE are specified in bytes, optionally with a k/M/G/T suffix. At present, SIZE may not exceed 4MB for a single request.
Our drive download tool automatically reads the drive in 4MB chunks. You should do the same for large downloads.

 

Write binary data to a drive
POST /drives/DRIVE/write[/OFFSET]
Expects Binary data (Content-Type: application/octet-stream)
Supports raw data or Content-Encoding: gzip
Does not support Transfer-Encoding: chunked
Returns HTTP 204 No Content
Notes OFFSET is the offset in the target drive at which to start writing, not an offset in the input stream. It is specified in bytes, optionally with a k/M/G/T suffix.
Our drive upload tool automatically splits the input file into 4MB chunks and transfers each chunk gzipped. You should do the same for large uploads.

 

Standard drives

Standard Drive Details

Pre-installed system images (gzipped)
UUID Description Size gunzipped
8d5c93b8-e4e4-4943-b41e-873576b7fcd1 CentOS Linux 6.5 1GB
ce85ef47-9794-4ed7-a8bd-af902ec0eddc Debian Linux 7.4 1GB
62f512cd-82c7-498e-88d8-a09ac2ef20e7 Ubuntu Linux 12.04 LTS 1GB
4f31382b-5098-4610-8993-bbebb844febd Ubuntu Linux 13.10 1GB
11b84345-7169-4279-8038-18d6ba1a7712 Windows Web Server 2008 R2 11GB
b23e81b9-103e-4f9d-8ce5-b57bb529007c Windows Web Server 2008 R2 + SQL Server 19GB
6c0c3072-f55f-4dd2-9308-951dacf41ce3 Windows Server 2008 Standard R2 9GB
63677762-4423-464f-92fd-5c43d449a716 Windows Server 2008 Standard R2 + SQL Server 19GB
cdea53be-2511-4c91-9779-f6421f623a49 Windows Server 2012 14GB
7b9807cc-3c92-425f-878c-1d45927f3f9c Windows Server 2012 + SQL Server 30GB

CD / DVD ISOs
UUID Description
86cfdea0-81c7-49c8-9689-1b38e65bbf09 CentOS Linux 6.0 Install CD
bed71b1c-ac2c-422c-8c7d-a2396951d2ee Debian Linux 6.0.1 Install CD
c9e6f5bc-834d-4b25-939e-9d21d1768f2b Ubuntu Linux 12.04 LTS Server Install CD
f89af28e-ff00-4fc9-a7ed-22e7fa5a88db Windows Server 2008 Trial Install CD
7aead6d3-c3e6-4940-85c7-f5ee61f6ef2b Windows Web Server 2008 Trial Install CD

Server API

Server API Details

List all servers
GET /servers/list
Returns for each server, a list of
SERVER CPU MEM

 

Get single server info
GET /servers/SERVER/info
Returns KEY VALUE pairs:
server SERVER
status active | stopped | paused | dumped | dead
user owner of the server
Also KEY VALUE pairs for server configuration (see below).
For an active server, also KEY VALUE pairs as follows:
started start time expressed in seconds since the epoch, in UTC
[rx|tx]:[bytes|packets] Cumulative received/transmitted byte/packet count for NICs
ide:BUS[0-1]:UNIT[0-1]:[read|write]:[bytes|requests]
scsi:BUS[0]:UNIT[0-7]:[read|write]:[bytes|requests]
block:INDEX[0-7]:[read|write]:[bytes|requests]
Cumulative i/o byte/request count for each drive

 

Get all servers info
GET /servers/info
Returns for each server, KEY VALUE pairs as server info

 

Create and optionally start a server
POST /servers/create (also starts the server)
/servers/create/stopped
Expects KEY VALUE pairs for server configuration (see below).
Returns KEY VALUE pairs as server info

 

Start a server
POST /servers/SERVER/start
Expects Empty POST
Returns HTTP 204 No Content

 

Set server configuration
POST /servers/SERVER/set
Expects For a stopped server, KEY VALUE pairs for server configuration (see below).
For an active server, only KEY VALUE pairs as follows:
name Server name
cpu CPU quota in core MHz
persistent ‘true’ means that server will revert to a ‘stopped’ status on server stop or shutdown, rather than being destroyed automatically
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
password Password for VNC access (maximum of 8 characters). If unset, VNC is disabled
Returns KEY VALUE pairs as server info
Notes Reconfigures a running server.

 

Stop a server
POST /servers/SERVER/stop
Expects Empty POST
Returns HTTP 204 No Content
Notes Kills the server immediately, equivalent to a power failure. Server reverts to a stopped status if it is persistent and is automatically destroyed otherwise.

 

Destroy a server
POST /servers/SERVER/destroy
Expects Empty POST
Returns HTTP 204 No Content
Notes Stops the server first if it active.

 

Shut down a server
POST /servers/SERVER/shutdown
Expects Empty POST
Returns HTTP 204 No Content
Notes Sends the server an ACPI power-down event. Server reverts to a stopped status if it is persistent and is automatically destroyed otherwise.

 

Reset a server
POST /servers/SERVER/reset
Expects Empty POST
Returns HTTP 204 No Content

 

Server configuration

Server Configuration Details

Key Value
name Server name.
cpu CPU quota in core MHz.
smp Number of virtual processors, or ‘auto’ to calculate based on cpu. When the server starts, this key stays unchanged, but two extra keys, “smp:cores” and “smp:sockets”, appear with the number of cores allocated and the number of sockets (virtual cpus) that these appear in.
mem virtual memory size in MB.
persistent ‘true’ means that server will revert to a ‘stopped’ status on server stop or shutdown, rather than being destroyed automatically.
ide:BUS[0-1]:UNIT[0-1]
scsi:BUS[0]:UNIT[0-7]
block:INDEX[0-7]
Drive UUID to connect as specified device.
ide:BUS[0-1]:UNIT[0-1]:media
scsi:BUS[0]:UNIT[0-7]:media
block:INDEX[0-7]:media
Media type – set to ‘cdrom’ to simulate a cdrom, set to ‘disk’ or leave unset to simulate a hard disk.
boot Device to boot, e.g. ide:0:0 or ide:1:0. Set to a list to make multiple devices bootable.
nic:0:model Create network interface with given type (use ‘e1000′ as default value; ‘rtl8139′ or ‘virtio’ are also available).
nic:0:dhcp The IP address offered by DHCP to network interface 0. If unset, no address is offered. Set to ‘auto’ to allocate a temporary IP at boot. When the server starts, this key stays unchanged, but an extra key “nic:0:dhcp:ip” appears with the IP allocated.
nic:0:firewall:policy Defines the action to be applied to all packets not matching an existing firewall rule. Possible values are ‘accept’ or ‘reject’.
This key only exists if the built-in firewall is in use, and setting it to any value will enable the firewall.
nic:0:firewall:accept Defines which, if any, inbound ports should be opened and to which protocols. Takes a space separated list in the form PROTOCOL/[IP ADDRESS]/[CIDR MASK]/PORT[:RANGE], eg. “tcp/22″ or “udp/10.0.0.0/16/5900:5902″. See the control panel firewall tooltip for more details.
This key only exists if the built-in firewall is in use, and setting it to any value will enable the firewall.
nic:0:firewall:reject Defines which, if any, inbound ports should be closed and to which protocols. Takes a space separated list in the form PROTOCOL/[IP ADDRESS]/[CIDR MASK]/PORT[:RANGE], eg. “tcp/22″ or “udp/10.0.0.0/16/5900:5902″. See the control panel firewall tooltip for more details.
This key only exists if the built-in firewall is in use, and setting it to any value will enable the firewall.
nic:1:model Create network interface with given type (use ‘e1000′ as default value; ‘rtl8139′ or ‘virtio’ are also available).
nic:1:vlan The VLAN to which the network interface is attached.
nic:1:mac The MAC address of the network interface. If unset, a randomly generated address is used. If set, should be unique on the VLAN.
vnc IP address for overlay VNC access on port 5900. Set to ‘auto’, to reuse nic:0:dhcp if available, or otherwise allocate a temporary IP at boot.
password Password for VNC access (maximum of 8 characters). If unset, VNC is disabled.
vnc:tls Set to ‘on’ to require VeNCrypt-style TLS auth in addition to the password. If this is unset, only unencrypted VNC is available.
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
avoid:drives optional, space-separated list of existing drives to ensure this new server is created on physical different hardware than those existing drives
avoid:servers optional, space-separated list of existing servers to ensure this new server is created on physical different hardware than those existing servers

 

Resource API (static IPs, VLANs, etc.)

Resource API Details

List all resources
GET /resources[/TYPE]/list
Returns for each resource, a list of
TYPE RESOURCE
Get single resource info
GET /resources/TYPE/RESOURCE/info
Returns KEY VALUE pairs:
name Resource name
type resource type (‘ip’, ‘vlan’, etc.)
resource resource identifier
user owner of the resource
netmask netmask to be used with a static IP
gateway gateway to be used with a static IP
nameserver name server to be used with a static IP
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
Get all resources info
GET /resources/info
Returns for each resource, KEY VALUE pairs as resource info
Create a resource
POST /resources/TYPE/create
Expects KEY VALUE pairs:
name Resource name
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
Returns KEY VALUE pairs as resource info
Set extra resource data
POST /resources/TYPE/RESOURCE/set
Expects KEY VALUE pairs:
name Resource name
tags optional, space-separated list of tags
user:* optional, user-defined KEY VALUE pairs
Returns KEY VALUE pairs as resource info
Destroy a resource
POST /resources/TYPE/RESOURCE/destroy
Expects Empty POST
Returns HTTP 204 No Content