API

API Tools

Quick Primer

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.

  • 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/

  • 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>

  • Create drive and upload image
  • We use the drive upload tool to automatically upload in gzipped chunks.

    $ 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

  • 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 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-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

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/full

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

 

ctags

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 kMGT 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

 

GET

/drives/DRIVE/read[/OFFSET]

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.

  • 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 Details

List all servers

 

GET

/servers/list

Returns

for each server, a list of SERVER CPU MEM

Get single server info

 

GET

GET

/servers/SERVER/info

Returns

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).

Returns

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 receivedtransmitted bytepacket 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 io byterequest 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 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. “tcp22″ or “udp10.0.0.0165900: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. “tcp22″ or “udp10.0.0.0165900: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

Doptional, space-separated list of tags

user:*

optional, user-defined KEY VALUE pairs

avoid:drives

optional, space-separated list of existing servers to ensure this new server is created on physical different hardware than those existing servers

avoid:servers

optional, user-defined KEY VALUE pairs

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

Get In Touch At sales@openhosting.com To Start Your Free Trial.