The following documentation is not officially supported by DreamHost. However, if you find any instructions in this article do not function as intended, it's possible it may be out of date. When in doubt, please contact support for further assistance.
What is an API?
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.
Does DreamHost have an API?
How does DreamHost's API work?
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:https://api.dreamhost.com/
And the plain text result is something like:
What values does DreamHost's API use?
- An API Key that you need to generate via the web panel.
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.
- The command you'd like to run. When you create your key you pick what command(s) it may access.
- You may pass a new unique_id (max length: 64 chars) when you submit a request, to make sure you don't accidentally submit the same command twice. Note that only successful queries "use up" a unique_id. DreamHost recommends using UUIDs for this purpose if you'd like. The unique_id you use only applies to your specific API key, so you never need to worry about any other users already "using" a specific unique_id.
Individual commands may have additional required values.
- The format you want to receive output in. Valid formats are:
- The account number to perform operations under. Defaults to your own account, or the first account you have access to otherwise.
All parameter names are case-sensitive and must be in lower case. However, the values you submit to the server are generally case-insensitive.
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.
If you wish to test the DreamHost API without having your own account, you may use the following API Key:
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.
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.
List of API modules
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.
Could you make X functionality accessible via the API?
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.
What sort of applications use the API?
A short list can be found at API Apps.