Making a Request

Below we have provided all the information you need to manually form an API request without using one of the above API wrappers.

The Endpoint {#endpoint}

You can make your API requests via HTTP POST requests starting from the following endpoint:

https://api.hostdime.com/v1/

For the security of your account, we only allow API requests to be made over HTTPS; any HTTP requests will fail outright.

Calling an API Method {#calling}

API modules are subdirectories within the endpoint, and the method you are calling is the page you are requesting. For example, if you are using the server.list action, your request URL might look like this:

https://api.hostdime.com/v1/server/list.json

Response Formats {#formats}

We currently support the following response formats:

  • JSON (.json)
  • XML (.xml)
  • Yaml (.yml)

Simply append the appropriate file extension to the API request:

https://api.hostdime.com/v1/server/list.json
https://api.hostdime.com/v1/ticket/create.xml
https://api.hostdime.com/v1/vps/stop.yml

JSONP {#jsonp}

Our API supports JSONP, simply add a callback parameter to a JSON request to generate a JSONP response.

Parameters {#parameters}

Any parameters to the request are simply provided as HTTP POST request parameters. An easy way to try this out is to use the utility.echo action:

POST /v1/utility/echo.json HTTP/1.1
Host: api.hostdime.com

foo=bar&faz=baz

Required Parameters {#required-parameters}

There are a few parameters that are required to make a restricted API request.

Parameter Description
api_key Your PUBLIC API key
api_timestamp The current Unix time (UTC)
api_unique A string unique to the request, to prevent duplicate requests
api_hash A specially formed hash of the API request. More details on its implementation below.

Generating the API Hash {#hash}

In order to generate the api_hash parameter, concatenate the fields in the following order with a colon, and then generate an SHA256 hash of the result:

  1. The Unix timestamp you provided with api_timestamp
  2. The unique identifier you provided with api_unique
  3. Your PRIVATE key
  4. The API method, like server.list or domain.forwarder.add
  5. A JSON encrypted string, of your JSON encrypted parameters object, in the order provided in the HTTP query, excluding any parameters prefixed with api_

So for the following request, assuming your public key is foobar and private key is fazbaz:

POST /v1/domain/list.json HTTP/1.1
Host: api.hostdime.com

status=registered&order=desc&api_key=foobar&api_timestamp=1369758680&api_unique=ABCDEF

The concatenated string would be:

1369758680:ABCDEF:fazbaz:domain.list:"{\"status\":\"registered\",\"order\":\"desc\"}"

And the resultant SHA256 hash would be:

499b5d8b8bce0f66d829d9186fb475c16b505ef7e6238c3b43c3342902ce27dd

So your final request would look like:

POST /v1/domain/list.json HTTP/1.1
Host: api.hostdime.com

status=registered&order=desc&api_key=foobar&api_timestamp=1369758680&api_unique=ABCDEF&api_hash=499b5d8b8bce0f66d829d9186fb475c16b505ef7e6238c3b43c3342902ce27dd

To avoid having to write all of this manually, we suggest using one of our provided API wrappers.