Application programming interface

From DreamHost
Revision as of 18:07, 1 February 2012 by Steven B (Talk | contribs)

Jump to: navigation, search

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?

Yes. Currently it does not offer all DreamHost functionality, but it's in heavy development!

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 we return the result 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:

 error
 no_key

Or maybe:

 success
 added_web

What values does DreamHost's API use?

Required

key
an API Key that you need to generate via our web panel.
cmd
the command you'd like to do... when you create your key you pick what command(s) it may access.
unique_id
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. We recommend 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.


  • note: individual commands may have additional required values

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.

Implementation Notes

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 our system remains stable and responsive, we have limited the rate at which certain API commands or groups of API commands can be run by the same user. These limits are relatively generous and very few users will 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 will 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 will be

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 will only be able to 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 would like to test the DreamHost API without having your own account, you may use the 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.

For Example

Example 1

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 do 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.

Could you make X functionality accessible via the API?

Maybe... maybe not! The point of our API is to make tasks that one person may want to do often available via a programming interface.. NOT to facilitate reselling of our services to multiple people. So that's pretty much how we'd decide if a certain feature should be API-able!

What sort of applications use the API?

There are dozens! We've been collecting them all at API Apps .. if you write your own app, feel free to add it there too!