DotBlock API v1

The DotBlock API allows you to manage your DotBlock accounts programmatically.

API access is enabled on all active DotBlock accounts. The API is available via HTTP at http://api.dotblock.com/v1/. This document outlines Version 1 (v1) of the DotBlock API.

API Authentication

All API requests require authentication using the email address (username) and password for your DotBlock account. Note that in these examples, the @ character in the username is replaced with %40. This is required if you pass the username via URL. Usage will depend on your client.

The API uses standard HTTP Basic Authentication. You can submit your username and password in the request, or by sending the HTTP Authorization header. The three examples below are equivalent.

Submit username and password via URL:

# GET /v1/ping
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/ping

Submit with username password via client:

# GET /v1/ping
curl http://api.dotblock.com/v1/ping -u "josh@dotblock.com:pwn13s"

Submit with HTTP Authorization header:

# GET /v1/ping
curl http://api.dotblock.com/v1/ping -H "Authorization: Basic am9zaEBkb3RibG9jay5jb206cHduMTNz=="

When using the Authorization header, the header must be in this format:

Authorization: Basic CREDENTIAL_HASH

CREDENTIAL_HASH should be a Base64 encoded string in the format username:password. Eg: base64_encode("josh@dotblock.com:pwn13s").

Response:

{"status":200,"response":"DotBlock API v1"}

In the event of authentication failure, the API will respond with a 401 Unauthorized message. Anytime authentication fails, the API returns the following payload:

{"status":401,"response":"Unauthorized"}

API Usage

The API uses RESTful resources and returns it’s payload in JSON format.

Managing Servers

To list your virtual servers:

# GET /v1/servers.json
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers.json

The API returns your server list in a hash. The format is:

{
  SERVER1_ID => {
    'mainipaddress' => IP,
    'hostname'      => HOSTNAME,
    'id'            => SERVER1_ID,
    'status'        => STATUS,
    'bandwidth'     => BANDWIDTH,
    'bandwidthused' => BANDWIDTH_USED
  },
  SERVER2_ID => {
    'mainipaddress' => IP,
    'hostname'      => HOSTNAME,
    'id'            => SERVER2_ID,
    'status'        => STATUS,
    'bandwidth'     => BANDWIDTH,
    'bandwidthused' => BANDWIDTH_USED
  }
  ...etc
}

The server ID is required for API actions that work with individual servers. If you attempt to submit a request using an invalid server ID, the following payload is returned:

{"status":200,"response":"Invalid server ID"}

The above request returns the following payload with 2 virtual servers with IDs 123456 and 123457:

{"status":200,"response":{"123456":{"mainipaddress":"66.147.235.0","id":123456,"hostname":"test.dotblock.com","status":"online","bandwidthused":"192472110","bandwidth":"536870912000"},"123457":{"mainipaddress":"66.147.235.1","id":123457,"hostname":"test1.dotblock.com","status":"online","bandwidthused":"192472110","bandwidth":"536870912000"}}}

To list a single server:

# GET /v1/servers/:id.json
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json

{"status":200,"response":{"mainipaddress":"66.147.235.0","id":123456,"hostname":"test.dotblock.com","status":"online","bandwidthused":"192472110","bandwidth":"536870912000"}}

You can perform the following actions on your virtual servers:

shutdown

# PUT /v1/servers/:id.json?action=shutdown
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json -X PUT -d "action=shutdown"

reboot

# PUT /v1/servers/:id.json?action=reboot
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json -X PUT -d "action=reboot"

boot

# PUT /v1/servers/:id.json?action=boot
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json -X PUT -d "action=boot"

suspend

# PUT /v1/servers/:id.json?action=suspend
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json -X PUT -d "action=suspend"

resume

# PUT /v1/servers/:id.json?action=resume
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/servers/123456.json -X PUT -d "action=resume"

The above actions return the following payloads:

# Successful (eg: reboot successful)
{"status":200,"response":"success"}

# Failure (eg: reboot failed)
{"status":200,"response":"error"}

Managing Client Info

To view your client information:

curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/account.json

Sample response:

{"status":200,"response":{"city":"Clifton Park","address1":"5 Corporate Drive","address2":"","country":"US","postcode":"12065","phonenumber":"1-555-555-5555","lastname":"Priddle","userid":45646789,"firstname":"Joshua","state":"NY","companyname":"Via:Talk"}}

To update your client information, submit a hash named info containing any of the following keys:

firstname lastname companyname address1 address2 city state postcode country phonenumber

For example, to update your first and last name:

# PUT /v1/account.json?info[firstname]=:firstname&info[lastname]=:lastname
curl http://josh%40dotblock.com:pwn13s@api.dotblock.com/v1/account.json -X -d "info[firstname]=James&info[lastname]=Bond"

When updating your client info, the API returns a new copy of your client info:

{"status":200,"response":{"city":"Clifton Park","address1":"5 Corporate Drive","address2":"","country":"US","postcode":"12065","phonenumber":"1-555-555-5555","lastname":"Bond","userid":45646789,"firstname":"James","state":"NY","companyname":"Via:Talk"}}

DotBlock Cloud Hosting

DotBlock API v1

API Authentication

API Usage

Managing Servers

Managing Client Info

Cloud Hosting

Features

Support

Company