Application programming interface overview

An application programming interface (API) is a source code interface that a computer system or program library provides to support requests for services to be made of it by a computer program. An API differs from an application binary interface in that it is specified in terms of a programming language that can be compiled when an application is built, rather than an explicit low level description of how data is laid out in memory.

The software that provides the functionality described by an API is said to be an implementation of the API. The API itself is abstract, in that it specifies an interface and does not get involved with implementation details.

A good example of an API would be a web service interface, such as the API provided by Google for its mapping service.

The DreamHost API is available in a simple "flat" interface, which is easy to use!

All you have to do is visit ("GET" or "POST" to) a simple URL (programmatically or even just with a web browser), and the result is returned as tab-delimited plain text (or other formats if you like).

That simple URL is:

And the plain text result is something like:

error
no_key

Or maybe:

success
added_web

Required

In order for a sub-account to create an API Key, it must be granted 'Billing' Account Privileges.

Please note that if a sub-account creates an API Key, it will only be visible to the sub-account on the API Key page in the panel. The primary account owner will not be able to view the sub-account's API Key in their panel.

Optional

format The format you want to receive output in. Valid formats are:

account The account number to perform operations under. Defaults to your own account, or the first account you have access to otherwise.

Case sensitivity

All parameter names are case-sensitive and must be in lower case. However, the values you submit to the server are generally case-insensitive.

Rate limit

In order to ensure that DreamHost systems remains stable and responsive, the rate at which certain API commands or groups of API commands can be run by the same user has been limited. These limits are relatively generous and very few users ever run into them. Limits are usually set per hour or per day, although some commands may have limits in shorter periods of time such as 10 minutes. When API calls fail for any reason (for example if you tried to create a user that already existed), it does not count against your limits (note that this also means that failing because you exceeded the rate limit also does not count). When you do run into a limit, the error returned is:

error
slow_down_bucko (detailed info about type of limit reached after a tab)

If you run into this error, you should consider ways in which you could reduce the frequency that you are calling the API. Most likely you would only run into these limits if you have a script or automated program that loops to repeatedly make API calls. So you can simply slow down the rate at which your script runs, or make sure that it keeps track of how many commands it has issued in the last hour/day.

Test Account

If you wish to test the DreamHost API without having your own account, you may use the following API Key:

6SHU5P2HLDAYECUM

This account only has access to "list" functions however (and only user-list_users_no_pw, not user-list_users) , as well as dreamhost_ps-set_size, dreamhost_ps-set_settings, and dreamhost_ps-reboot to ps7093.

An example

https://api.dreamhost.com/?key=6SHU5P2HLDAYECUM&cmd=user-list_users_no_pw&unique_id=4082432&format=perl

If you are writing a simple bash script to interface with DreamHost's API, this may help as a start:

#!/bin/sh
####
#### USE THIS SCRIPT AT YOUR OWN RISK.  
####

PS=$1

KEY=YOUR-KEY-HERE
UUID=`uuidgen`
CMD=user-list_users_no_pw
 
if [ $# -lt 1 ]; then
 	echo "usage: `basename $0` [hostname]" 
	exit 1
fi

if [ "$PS" = "" ]; then
	PS=`hostname | cut -f1 -d.`
fi 

# ARGS='other_http_get_arguments_for_the_DreamHost_cmd_that_you_are_using=4&foo=123'
LINK="https://api.dreamhost.com/?key=$KEY&unique_id=$UUID&cmd=$CMD&ps=$PS&$ARGS"

RESPONSE=`wget -O- -q "$LINK"`

echo "$LINK"
echo "$RESPONSE"
if ! (echo $RESPONSE | grep -q 'success'); then
	exit 1
fi

# Now use the content of $RESPONSE to do whatever you wish.
#
# Rinse, lather, repeat.

API commands are grouped into modules. All the commands in a module will start with module_name-

Detailed information about API commands such as values you need to send and the format of the results can be found on the documentation page for each module, which are listed in the See also section below.

The point of the API is to make tasks that one person may want to often do available via a programming interface — not to facilitate reselling of services to multiple people. That is how DreamHost decides if a certain feature should be incorporated into the API.

A short list can be found at API Apps.