API

Explore cloud servers

ElasticHosts virtual servers come in sizes to suit all businesses, from a basic, but fully capable server from £29 per month to high-end configurations with up to eight cores, 8 GB memory, 2 TB disk.

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 and a drive upload tool for Unix or Windows Cygwin users to control our infrastructure from their own scripts without writing any code.

Worked example

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, using our simple command line tool and drive upload tool 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
      $ # Substitute api.lon-b.elastichosts.com if your account is there.
      $ # Alternatively, you can hard-code the value of EHURI in your local
      $ # copy of the scripts.
      $ export EHURI=https://api.lon-p.elastichosts.com/
      $ # Set authentication credentials (from 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 EHAUTH in your local
      $ # copy of the scripts, but make sure they aren't world-readable!
      $ export EHAUTH=<user uuid>:<secret API key>
      $ # Create drive and upload image
      $ # We use the drive upload tool to automatically upload in
      $ # gzipped chunks. A more basic upload with the raw API would be:
      $ # elastichosts -c drives create << EOF | grep drive
      $ # > name TestDrive
      $ # > size 10000000
      $ # > EOF
      $ # drive 08c92dd5-70a0-4f51-83d2-835919d254df
      $ # elastichosts -f image.raw drives 08c92dd5-70a0-4f51-83d2-835919d254df write
      $ elastichosts-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
      $ elastichosts -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.lon-p.elastichosts.com/ where lon-p refers to the availability zone for our Peer 1 availability zone near London 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:

            name TestServer
            cpu 4000
            mem 2048

            {"name":"TestServer", "cpu":4000, "mem":2048}
            

            ip 192.168.0.1
            ip 192.168.0.2
            ip 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"}]
            

            name TestServer1
            cpu 2000
            mem 1024
            name TestServer2
            cpu 4000
            mem 2048

             [{"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:

Drive API

Standard drives

Server API

Server configuration

Resource API (static IPs, VLANs, etc.)