Voxel's Hosting API (hAPI)

Voxel's Hosting API (hAPI) turns the functionality that Voxel has developed over the years inside out, exposing it to our customers with advanced needs. Through hAPI, these customers will be able to manage and monitor all their Voxel services, using the programming language of their choice.

In line with our core philosophy, hAPI is built upon an open, standards based, fully documented platform. It is available to all customers at no additional charge.

hAPI is an evolving Voxel product. Over the coming months we'll expose more and more of our functionality via hAPI methods. hAPI will grow to include:

  • Devices: provisioning, backups, metrics, monitoring
  • Domains: management via Voxel's DNS servers
  • VoxCAST CDN: content management (purging, cache pre-population, etc.), traffic and performance metrics, configuration, testing
  • Support: ticket management, summaries, reports
  • Billing: payment, tracking

hAPI's initial release is focused on VoxCAST.

Technology Overview

hAPI is a RESTful API based on HTTP requests and XML or JSON responses. Each hAPI request is authenticated. If you're familiar with the APIs of Flickr, Amazon's S3, del.icio.us, or a host of other web services, you'll feel right at home with Voxel's hAPI, and may even be able to take advantage of existing code.

This document gives a basic technical overview of hAPI and describes the available hAPI methods, including their inputs, actions, and outputs. If you need help or have questions about hAPI, just ask.

hAPI Toolkits

Voxel's customers build their applications on a variety of platforms. Several of them have written toolkits for interacting with hAPI, and have been kind enough to share. If you have hAPI code you'd like to share (or that you need help with) let us know!

Request Formats

To call a hAPI method, make a simple HTTP GET or POST request.

The Voxel hAPI endpoint URL is:

http://api.voxel.net/

All the hAPI methods are in the "voxel" namespace and are called something like "voxel.group.methodName". To call the "voxel.test.echo" method, request:

http://api.voxel.net/?method=voxel.test.echo&name=value&[auth_params]

where the auth_params part of the request is explained below.

Response Formats

Responses are either XML (the default) or JSON. You can control the response format by passing the format parameter (the value should be either "xml" or "json"). For example:

http://api.voxel.net/?method=voxel.test.echo&nam=value&[auth_params]&format=json

returns a JSON response. The two response formats are detailed below.

XML Responses

Methods respond in a simple XML format by default:

<?xml version="1.0"?>
<rsp stat="ok">
	[xml-payload-here]
</rsp>

When there is an error, the response is instead like:

<?xml version="1.0"?>
<rsp stat="fail">
	<err code="[error-code]" msg="[error-message]"/>
</rsp>

JSON Responses

JSON responses are directly analogous to their XML counterparts. There are two important points:

  • Data that would be represented as attributes of an element in an XML response (i.e., '<element attribute="value">...') is available as "attributes" in the JSON object, e.g., '{"element":{"attributes":{"attribute":"value"}}}'.
  • There is no top-level "rsp" element; the response starts with what would be the attributes of "rsp" in an XML response.

A successful JSON response looks like:


{
	"attributes" : {
		"stat" : "ok"
	},
	[json-payload-here]
}

When there is an error, the response is instead like:


{
	"attributes" : {
		"stat" : "fail"
	},
	"err" : {
		"attributes" : {
			"code" : "[error-code]",
			"msg" : "[error-message]"
		}
	}
}

API-wide Error Codes

Several error codes are global across all hAPI methods. These are:

1: Invalid login or password
Authentication for the request failed because either user or api_sig was incorrect.
2: Unspecified API method
The method parameter doesn't exist or is not a valid hAPI method.
3: Request time too different from server time
The timestamp parameter is too different from the hAPI server's current time. Make sure to synchronize your clock, e.g., using NTP.
4: Backend error, please try again shortly
hAPI had trouble communicating with one of Voxel's other systems (e.g., a CDN node or a device management server). If this problem persists, please contact us.
5: Missing method-specific parameters
Some parameters required by the particular method being called were omitted.
6: Parameters are invalid
Some parameters passed to the method are in an incorrect format or are otherwise unusable.

Authentication

Every request to hAPI must include three authentication parameters:

  • user: the customer's hAPI username -- the same username you use to log into Ubersmith or the VoxCAST Portal.
  • timestamp: the current timestamp in ISO 8601 format. This can be obtained in PHP with date(DATE_ISO8601). The timestamp must be within 15 minutes of the hAPI server's NTP-synchronized time.
  • api_sig: the MD5 hash of a request-specific string. The string is computed by first concatenating all of the GET/POST variables sent with the request, like "key1value1key2value2...", in alphabetical order by variable name. This includes user and timestamp. Concatenate this string to the end of the "secret": your hAPI password -- the same one you use to log into Ubersmith or the VoxCAST Portal. Finally, compute the MD5 hash of the string. The following PHP code fragment computes api_sig given the GET and POST variables and the password: 
    
function compute_signature($get, $post, $secret)
{
  $vars = array_merge($get, $post);
  ksort($vars);
  $string = $secret;
  foreach($vars as $k => $v)
    if($k != 'api_sig')
      $string .= $k . $v;
  return md5($string);
}

So, a complete hAPI request will look something like:

http://api.voxel.net/?method=voxel.test.echo&foo=bar&user=voxel
  ×tamp=2008-10-09T13:10:43-0400&api_sig=910e0850e49608d7c7a2ab05cf68b15f

hAPI Terms of Use

Creative Commons License
Voxel Hosting API Specification by Voxel dot Net, Inc. is licensed under a Creative Commons Attribution 3.0 United States License.

In keeping with Voxel's open philosophy, hAPI's specification is published under the Creative Commons Attribution 3.0 license. This means other companies in Voxel's space are free to build compatible APIs, including extensions to better suit their own customers.

Voxel's customers who make use of hAPI are subject to Voxel's standard policies and SLAs, along with any separate agreements specifically made between Voxel and the customer.