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://us-east.crosspeer.com/api/
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:
Using the Cloud Computing API
Multiple lines of text, each containing a key, followed by a space, followed by the value: e.g.
name TestServer
cpu 4000
men 2048
Data is accompanied by the HTTP header
'X-Elastic-Output: properties'
name TestServer
cpu 4000
men 2048
Data is accompanied by the HTTP header
'X-Elastic-Output: properties'
Single object, key value pairs or properties
Multiple objects, list of values
Multiple objects, key value pairs of properties for each
JSON object: e.g.
{"name":"TestServer", "cpu":4000, "mem":2048}
{"name":"TestServer", "cpu":4000, "mem":2048}
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.1
ip 192.168.0.1
Data is accompanied by the HTTP header
'X-Elastic-Output: list'
ip 192.168.0.1
ip 192.168.0.1
ip 192.168.0.1
Data is accompanied by the HTTP header
'X-Elastic-Output: list'
JSON array of obejects: e.g.
[{"type":"ip", "resource":"192.168.0.1"},
{"type":"ip", "resource":"192.168.0.2"},
{"type":"ip", "resource":"192.168.0.3"}]
[{"type":"ip", "resource":"192.168.0.1"},
{"type":"ip", "resource":"192.168.0.2"},
{"type":"ip", "resource":"192.168.0.3"}]
Multiple lines of text, each containing a key, followed by a space, followed by the value. Blank lines separting objects: e.g.
name Testserver1
cpu 2000
mem 1024
name Testserver2
cpu 4000
mem 2048
name Testserver1
cpu 2000
mem 1024
name Testserver2
cpu 4000
mem 2048
JSON array of objects: e.g.
[{"name":"TestServer1", "cpu":2000, "mem":1024},
{"name":"TestServer2", "cpu":4000, "mem":2048}]
[{"name":"TestServer1", "cpu":2000, "mem":1024},
{"name":"TestServer2", "cpu":4000, "mem":2048}]
text/plain
application/json
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:
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 full
|
Drive API
List all drives
|
|
GET
|
/drives/list
|
Returns
|
for each drive, a list of DRIVE
|
Get single drive info
|
|
GET
|
/drives/DRIVE/info
|
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
|
Returns 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
|
KEY VALUE pairs:
|
|
name
|
drive name
|
size
|
size of drive in bytes
|
claim:type
|
optional, either 'inclusive' (the default) or 'shared' to allow multiple servers to access a drive simultaneously
|
Expects readers
|
optional, space-spearted 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-sts-plain' (the default)
|
Returns
|
KEY VALUE pairs as drive info
|
Destroy a drive
|
|
POST
|
/drives/DRIVE/destroy
|
Expects
|
Empty POST
|
Returns
|
HTTP 204 No Content
|
Set extra drive data
|
|
POST
|
/drives/DRIVE/set
|
KEY VALUE pairs:
|
|
name
|
Drive name
|
size
|
size of drive in bytes
|
Expects 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, usually 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] Binary data (Content-type: application/octet-stream)
|
Expects
|
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
UUID
|
Description
|
Size gunzipped
|
38df0986-4d85-4b76-b502-3878ffc80161
|
CentOS Linux 5.5
|
1GB
|
980cf63c-f21e-4382-997b-6541d5809629
|
Debian Linux 6.0
|
1GB
|
aee5589a-88c3-43ef-bb0a-9cab6e64192d
|
Ubuntu Linux 10.04
|
1GB
|
b9d0eb72-d273-43f1-98e3-0d4b87d372c0
|
Windows Web Server 2008
|
13GB
|
30824e97-05a4-410c-946e-2ba5a92b07cb
|
Windows Web Server 2008 R2
|
13GB
|
9ecf810e-6ad1-40ef-b360-d606f0444671
|
Windows Web Server 2008 R2 + SQL Server
|
13GB
|
10a88d1c-6575-46e3-8d2c-7744065ea530
|
Widnows Web Server Standard
|
13GB
|
2567f25c-8fb8-45c7-95fc-bfe3c3d84c47
|
Windows Web Server Standard R2 + SQL Server
|
13GB
|
Pre-installed system images (gzipped)
UUID
|
Description
|
b86afe3a-b5dc-4184-9ef0-3a52dce63238
|
CentOS Linux 5.3 Install CD
|
ac646eda-62be-4366-8cc9-10afdf6506b5
|
CentOS Linux 5.4 Install CD
|
5f029de7-1729-486b-9bb3-65e326febb4d
|
CentOS Linux 5.5 Install CD
|
adb59223-edcf-418f-a74c-8a9b4788e1d6
|
Debian Linux 5.0 Install CD
|
86f52611-567b-40b9-8db7-933ad4f483d7
|
FreeBSD 7.2 Install CD
|
a080dce0-2f28-4e42-9db6-1c5f410a3da8
|
FreeBSD 8.0 Install CD
|
a1cd7ea0-6539-4cb6-b35f-03c9a6b61917
|
Knoppix Linux 6.0.1 Live CD
|
b36bd91f-ce93-45c3-946a-d095018681c0
|
OpenSolaris 2009 06 Install CD
|
c06a0aa9-9919-4e0f-92a0-c67b6799a732
|
Red Hat Fedora Linux 10 Install CD
|
9b283809-2990-4f3b-a4e9-8b59a417536c
|
Red Hat Fedora Linux 10 Live CD
|
b3df1320-5f11-4ebd-bd8c-2eef0e2ffe0d
|
Red Hat Fedora Linux 11 Install CD
|
bf3cf10d-d07b-47de-b79c-327983182ef0
|
Red Hat Fedora Linux 11 Live CD
|
d10281f4-3bf1-4a98-bc0c-6dcec04fd995
|
Red Hat Fedora Linux 12 Install CD
|
c0ae458c-d5fb-4d9c-ae3c-778c12fe0649
|
Red Hat Fedora Linux 12 Live CD
|
d2511065-1d4f-46e5-936a-c6b5c32a7556
|
Red Hat Fedora Linux 13 Install CD
|
853bb98a-4fff-4c2f-a265-97c363f19ea5
|
Red Hat Fedora Linux 13 Live CD
|
5d63810b-6e11-4a26-a820-9e0e92c2f35c
|
Ubuntu Linux 8.04.2 LTS Server Install CD
|
b06b793a-2aa6-433b-80b2-1863eacd3391
|
Ubuntu Linux 8.10 Server Install CD
|
95a324fd-3e45-498d-812f-98778bd127b9
|
Ubuntu Linux 9.04 Server Install CD
|
c90a801d-679e-4647-81ac-3146da724c62
|
Ubuntu Linux 9.10 Server Install CD
|
37e0f871-8a71-4b15-9478-ada0109dcce5
|
Ubuntu Linux 10.04 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
|
CD / DVD ISOs
Server API
List all servers
|
|
GET
|
/servers/list
|
Returns
|
for each server, a list of SERVER CPU MEM
|
Get single server info
|
|
GET
|
/servers/SERVE/info
|
KEY VALUE pairs:
|
|
server
|
SERVER
|
status
|
active | stopped | paused | dumped | dead
|
user
|
owner of the server
|
KEY VALUE pairs for server configuration (see below)
|
|
Returns KEY VALUE pairs (for an active server)
|
|
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]:[byte|requests]
|
Cumulative I/O byte/request count for each drive
|
block:INDEX[0-7]:[read/write]:[bytes|requests]
|
|
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
|
For a stopped server, KEY VALUE pairs for server
confguration (See below).
|
|
name
|
Server name
|
cpu
|
CPU quota in core MHz
|
Expects
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
|
vnc: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 serer 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 teh server first if it is 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 destroed otherwise.
|
Reset a server
|
|
POST
|
/servers/SERVER/reset
|
Expects
|
Empty POST
|
Returns
|
HTTP 204 No Content
|
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" appear with the number of cores allocated and teh 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]
|
Drive UUID to connect as specified device
|
block:INDEX[0-7]
|
|
ide:BUS[0-1]UNIT[0-1]:media
|
|
scsi:BUS[0]:UNIT[0-7]:media
|
Media type - set to 'cdrom' to simulate a cdrom, set to 'disk' or leave unset to simulate a hard disk
|
block:INDEX[0-7]:media
|
|
boot
|
Device to boot, e.g. ide: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:1:model
|
Create network interface with given tpe (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
|
vnc:password
|
Password for VNC acess (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
|
Server Configuration
Resource API (static IPs, VLANS, etc.)
List all resources
|
|
GET
|
/resources[TYPE]/list
|
Returns
|
for each reource, a list of TYPE RESOUCE
|
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
|
nameserver 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
|
KEY VALUE pairs
|
|
Expects 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
|
KEY VALUE pairs
|
|
Expects 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
|
