Open Hosting API

Open Hosting’s HTTP API allows users to create and control drives and 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.

Quick Primer: Upload a Drive & Boot a Server

Here is the full input and output of two examples of uploading your own server image using our simple command line tool and drive upload tool on Unix or Windows Cygwin (during the Cygwin installation be sure to install the cURL packages). 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 East1

Before we start you’ll need to set the API end-point. Alternatively, you can hard-code the value of OHURI in your local copy of the scripts.

$ export OHURI=https://api-east1.openhosting.com/

2. Set authentication credentials (from account profile)

Next, set authentication credentials, which can be found on your account profile page. Omit the secret key if you are running on a very old unix which 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 OHAUTH in your local copy of the scripts, but make sure they aren’t world-readable!

$ export OHAUTH=<user uuid>:<secret API key>

3. Create drive and upload image

Use the drive upload tool to automatically upload in gzipped chunks. This method also has the benefit of implicitly creating a drive at the time the image is uploaded.

$ openhosting-upload image.raw
Created drive 08c92dd5-70a0-4f51-83d2-835919d254df of size 10000000
Uploading 2 chunks of 5242880 bytes: .. completed

Alternatively, explicitly create the drive and then upload the image into the drive.

$ openhosting -c drives create << EOF | grep drive
$ > name TestDrive
$ > size 10000000
$ > EOF
$ drive 08c92dd5-70a0-4f51-83d2-835919d254df
$ openhosting -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.

$ openhosting -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 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-east1.openhosting.com/.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

List all drives

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

Get single drive imaging status

GET /drives/DRIVE/info
Returns Status: active | inactive

Get single drive info

GET /drives/DRIVE/info/full
KEY VALUE pairs:
Returns 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
KEY VALUE pairs:
Expects 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
KEY VALUE pairs:
Expects 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

Pre-installed system images (gzipped)
UUID Description Size gunzipped
1fc52c4b-f08d-4f9f-8821-7fdd073a32d6 CentOS Linux 5.5 1GB
4d67096a-c2b5-4be7-9716-d4b2f9e2d4b5 CentOS Linux 5.6 824MB
61e04f61-a39e-494f-bcf6-b17d3eba0df7 CentOS Linux 5.7 188MB
aaadb4ed-3694-4fa8-a3ba-f4a4f820b2a0 CentOS Linux 6.2 184MB
9c1a506a-5d2b-496b-9ebc-26cfeae76f42 Debian Linux 5.0 104MB
13658a54-4086-47a4-89cb-ae21da7afb0c Debian Linux 6.0 136MB
ddfec3ef-1366-4901-a776-b70af62ebb94 Ubuntu Linux 10.04 Desktop 672MB
8023b089-7b0e-4fcb-8016-01e82f2a9716 Ubuntu Linux 10.04 Server 156MB
bdb0cb41-9c86-46d8-bd39-29286c7d4ddb Ubuntu Linux 11.10 212MB
594e3d40-a7eb-471a-94d6-2be21eb39f86 Windows Web Server 2008 R2 5GB
fcdc0335-4bb6-455a-9030-a785719ddc72 Windows Web Server 2008 R2 + SQL Server 11GB
d7826937-a160-4f70-ab5a-7ee9d78f7404 Windows Server 2008 Standard R2 5GB
CD / DVD ISOs
UUID Description
3f6119b4-5dff-40be-a450-5e1f8ae32a18 CentOS Linux 5.5 Install CD
ba1b22ca-4144-4581-8bd5-0ee4261641b6 CentOS Linux 6.2 Install CD
5ba4b538-1c25-44c7-8d8a-5a4a2e45287c Debian Linux 5.0 Install CD
7e55f9be-a795-4963-8a8e-9fa8c5d5db10 Red Had Fedora Linux 15 Install CD
2938a3f4-e2f9-4c9f-84eb-410564f55e63 Red Had Fedora Linux 16 Install CD
0013a9ab-aea9-4e12-930e-e30cf840d71e FreeBSD 9.0 Install CD
c976c509-8e3c-4fa5-9a2d-dde2db8d81e4 Oracle Solaris 10 Install CD
62383356-9b16-40f0-b625-7a91c0c6ed0c Oracle Solaris 11 Install CD
ee26b956-c421-47d6-abcc-aab0dde12d42 Ubuntu Linux 10.04 Server Install CD
d29b068b-d86c-40a4-b613-03a3c9753ac4 Ubuntu Linux 10.10 Desktop Install CD
25530ec2-bed3-43cb-b5e3-17fdc922a17a Ubuntu Linux 10.10 Server Install CD
89535245-bad9-4d80-a0d8-ce1d6dc075c9 Ubuntu Linux 11.04 Desktop Install CD
9df0d067-da65-4ece-9158-cad4add96247 Ubuntu Linux 11.10 Server 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
KEY VALUE pairs:
server SERVER
status active | stopped | paused | dumped | dead
user owner of the server
Returns 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
For a stopped server, KEY VALUE pairs for server configuration (see below).
For an active server, only KEY VALUE pairs as follows:
Expects name Server name
cpu CPU quota in core MHz
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
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

Key Value
name Server name.
cpu fireCPU 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: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

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
KEY VALUE pairs:
Returns 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
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