Using the API & CLI

Our HTTP API allows users to create drives, upload and download drive images and create and control virtual servers on our infrastructure. The API works in a straightforward ReST style, and we also provide a simple command line tool, drive upload tool and drive download tool for Unix or Windows Cygwin users to control our infrastructure from their own scripts without writing any code.

Using the CLI

In only two commands, you can upload a drive image and boot a server. Here is the full input and output to do exactly this, on Unix or Windows Cygwin. Each command corresponds 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.

    $ # Set API end-point for your availability zone
    $ export SLURI=https://api.z1-man.serverlove.com/
    $ # Set authentication credentials (from account profile)
    $ export SLAUTH=<user uuid>:<secret API key>
    $ # Create drive and upload image
    $ love-upload image.raw
    Created drive 08c92dd5-70a0-4f51-83d2-835919d254df of size 10000000
    Uploading 2 chunks of 5242880 bytes: .. completed
    $ # Boot a server from the drive, with 2000 core MHz and 1024 MB RAM
    $ love -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
    > vnc:ip auto
    > vnc:password XXXXXXXX
    > EOF
    server 85ef58c8-6f5d-4f7f-8f1c-0c19d45d7c1c
    name TestServer
    cpu 2000
    smp 1
    mem 1024
    ide:0:0 08c92dd5-70a0-4f51-83d2-835919d254df
    boot ide:0:0
    nic:0:dhcp 91.203.56.132
    nic:0:model e1000
    rx 0
    tx 0
    vnc:ip 91.203.56.132
    vnc:password XXXXXXXX

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.z1-man.serverlove.com/ where z1-man refers to the availability zone for our Manchester 1 availability zone 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
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 percentage completed of drive imaging if this is underway, or ‘queued’ if waiting for another imaging operation to complete first
[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.
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 chunks and transfers each chunk gzipped. You should do the same for large uploads.

Standard drives

UUID Description Minimum Size
679f5f44-0be7-4745-a658-cccd4334c1aa CentOS Linux 5.5 1GB
5f2e0e29-2937-42b9-b362-d2d07eddbdeb Ubuntu Linux 10.04 1GB
5795b68f-ed26-4639-b41d-c93235062b6b Debian Linux 5 1GB
41993a02-0b22-4e49-bb47-0aa8975217e4 Windows Server 2008 R2 Standard 15GB
85623ca1-9c2a-4398-a771-9a43c347e86b Windows Web Server 2008 R2 15GB

CD / DVD ISOs

UUID Description
77cbac01-e09e-4279-84be-b2d5cd4a9116 Ubuntu 10.04 Desktop Live CD
bf726862-6232-41d2-b300-9c493564be9d Ubuntu Linux 10.04.1 Server Install CD
7e47f4a8-4871-400e-8b95-c55d6fda55f6 Fedora Linux 13 Live CD
73ac0200-d2cb-485e-adbd-8a6d23a7c500 Fedora Linux 13 Install CD
d7977204-f8c7-4a8b-a646-5760df5bc69f FreeBSD 8.1 Install CD
f6e11415-324a-4b17-b2c9-22833ee26ec0 Knoppix Linux 6.2 Live CD
22d27b47-ea27-4e3a-be50-4de62dbb04a2 OpenSolaris 2009.06 Install CD
7b479f5e-7ad7-4858-96da-0dc041c8b2c5 CentOS Linux 5.5 Install CD
8cb262a3-32ff-4ac8-917f-bd5de8be3acf Debian Linux 5.0 Install CD
ba9e9479-326c-4b90-baa5-8593c51d765f Windows Server 2008 R2 Install CD

Server API

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
vnc:password Password for VNC access. 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

Key Value
name Server name.
cpu CPU quota in core MHz.
smp number of virtual processors or ‘auto’ to calculate based on cpu.
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.
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 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.
vnc:password Password for VNC access. 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

Resource API (static IPs, VLANs, etc.)

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
 
21 queries. 0.219 seconds.