API | Open Hosting, Inc | Cloud Computing KVM Hosting Server Business Solution

Cloud Platform API

Open Hosting’s 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.

API Examples: Two Ways to Upload a Drive (AKA “Bring Your Own 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.

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/

And, next set authentication credentials (from your account profile). 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>

In these examples, we use the drive upload tool to automatically upload in gzipped chunks. A more basic upload with the raw API would be:

In the first example, we’ll create the drive in your account, then we’ll 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

This second example creates a drive implicitly 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

Now, let’s 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
> 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-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.

Click each box to reveal more information or you can expand or collapse all of the boxes:
Expand All | Collapse All

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}

HTTP status code	X-Elastic-Error	Explanation
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
	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
	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 ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously
Expects	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	Y VALUE pairs as drive info
Notes	size is specified in bytes, optionally with a k/M/G/T suffix.

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:

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.

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

	KEY VALUE pairs:
Expects	name	Resource name
	tag	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

Cloud Platform API

API Examples: Two Ways to Upload a Drive (AKA “Bring Your Own Server”)

Using the API

Authentication

Data formats

Recent Posts

Categories