API tutorial

Updated Dec 29 at 10:40 CDT (first posted Dec 7 at 02:53 CDT) by remi in API, Python, Rails  - 7 comment(s)

• Introduction
• Getting started
• Creating an e-mail address
• Installing an application
• Packaging the install script for the control panel
• Making your script available in one-click to other users

Introduction

The WebFaction API allows you to write scripts to automate certain tasks that you would normally accomplish via our control panel or via SSH.

For instance, you could use this API to write a script to configure lots of e-mail addresses (instead of creating them one by one in the control panel).

You can also use this API to automate the installation of any application that you like and most importantly, you can share this install script and allow other users to use it in one click !

Getting started

The API is a set of methods available via XML-RPC calls at the URL "https://api.webfaction.com/". In this tutorial we will use the Python programming language to talk to the API but you can use any language that you want, provided that this language has an XML-RPC library.

The first thing to do is to is to connect to the server and to login:

>>> import xmlrpclib >>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/') >>> session_id, account = server.login('test5', 'password') >>> account {'username': 'test5', 'home': '/home2', 'id': 237}

The username and password passed to the login method are the ones from the control panel.

As you can see, the "server.login" method returns a tuple. The first element is a string containing a session_id that you will need to pass to all subsequent methods. The second element is a dictionary containing various data about your account, including the base home directory (usually /home or /home2).

Creating an e-mail address

As a first example, let's create a new e-mail address for our account:

>>> server.create_email(session_id, 'user@mytestdomain.com', 'test5') {'email_address': 'user@mytestdomain.com', 'id': 2037, 'targets': 'test5'}

The create_email method takes the session_id, the e-mail address and the targets. It returns a dictionary containing various data about the newly created e-mail address.

This call is equivalent to creating the e-mail address from the control panel but the advantage is that you can script it :)

Installing an application

Now let's see which methods we can use to install an application. For this tutorial, let's install a Joomla application.

The first thing to do is to create a "Static/CGI/PHP" application, like this:

>>> server.create_app(session_id, 'my_joomla_app', 'static', False, '') {'app_type': 'static', 'name': 'my_joomla_app', 'id': 3901, 'autostart': False, 'port': 0, 'extra_info': ''} The parameters to create_app are:

• session_id
• name: the name of the application
• type: the type of the application. This can be any of the "base" types supported by the control panel. The main ones are "static", "custom_app_with_port", "rails_116", "django_095", "turbogears_10b1", ...
• autostart: either True or False (see control panel for what it means)
• extra_info: see control panel for what it means

Calling create_app is equivalent to creating the application through the control panel: it creates the directory and configures everything that's needed for this application.

The next thing to do is to download the Joomla tarball and to untar it in the app directory. To do so we'll use the system method of the API, which allows us to execute some command on our server as if we were logged in with SSH. Since the default static/cgi/php app comes with an "index.html" file which would shadow the "index.php" file provided by Joomla we also delete that file:

>>> cmd = "rm -f index.html;" >>> cmd += "wget http://wiki.webfaction.com/attachment/wiki/JoomlaFiles/Joomla_1.5.0-Beta-Full_Package.tar.gz?format=raw > /dev/null 2>&1;" >>> cmd += "tar xzvf Joomla_1.5.0-Beta-Full_Package.tar.gz?format=raw > /dev/null 2>&1;" >>> server.system(session_id, cmd) ''

The system method returns whatever the command printed on stdout. If the command prints something on stderr, system raises an error with that text.

Note that the system method (and other methods that perform some work on your SSH account) put you in the app directory by default before performing the work. This is quite handy since it saves you from having to "cd" into that directory every time.

The next thing we need to do is to create a MySql database (Joomla needs one to run):

>>> server.create_db(session_id, 'test5_joomla_db', 'mysql', 'db_password') {'type': 'mysql', 'id': '116101115116053095106111111109108097095100098045109121115113108', 'name': 'test5_joomla_db'}

This creates a mysql database called "test5_joomla_db" and a user called the same, with the password "db_password".

The next step is to copy the Joomla config file from "configuration.php-dist" to "configuration.php" and then edit it to specify the database connection settings:

>>> server.system(session_id, "cp configuration.php-dist configuration.php;") '' >>> server.replace_in_file(session_id, 'configuration.php', ("var $user = '';", "var $user = 'test5_joomla_db';"), ("var $password = '';", "var $password = 'db_password';"), ("var $db = '';", "var $db = 'test5_joomla_db';")) ''

Note the handy replace_in_file method which takes a session_id, the name of the file and then any number of tuples containing which string should be replace by which other string.

Another handy method to write to a file is write_file, which works like this:

>>> server.write_file(session_id, 'my_file', 'my_data', 'wb') ''

There are a few other steps needed to install a Joomla app: we need to edit the Joomla sql file and run it. We won't detail them here but you can find the actual script on this page

Packaging the install script for the control panel

In the previous paragraph we've installed a Joomla application by manually running a bunch of commands. It is possible to package these commands in an install script and to have the control panel run this script for us. The advantage is that we can then run this install script over and over again directly from the control panel and we can also share it with other people.

How the control panel will call the script

When you create an application in the control panel, all you have to do is choose "Custom install script" under "app type". When you do that the control panel will display an additional "Script URL" field. If you click on the "view/hide" script link next to it it will display a new field called "Script code". You can paste your script code in there and the control panel will run it when you press "Create".

The control panel expects a script that it will call with the following parameters:

install_script create|delete username password app_name autostart extra_info

username and password are the control panel username and hashed password for the user trying to create the app. app_name, autostart and extra_info are the value entered by the user on the "create app" page.

When the user creates the app, the control panel will call your script with "create" as the first parameter. If the user deletes the app later on, the control panel will call your script with "delete" as the first parameter.

When it calls your script with "create", the control panel expects your script to print the app id to stdout, and only that. If you script prints anything else to stdout, or prints anything to stderr the control panel will display it as an error message on the app creation screen.

When it calls your script with "delete", the control panel expects your script to not print anything to stdout or stderr. If anything gets printed the control panel will display it as an error message.

Also, if your script is written in Python and you include a docstring at the beginning of the script it will get used by the control panel as the app documentation.

To see two examples of install scripts, have a look a the Joomla install script or the MoinMoin install script

Making your script available in one-click to other users

Now that you have your install script, one way to share it would be to simply tell people to copy and paste it in the control panel when they create an application. But there is a better way ... :)

On the "Create app" screen in the control panel, there is a field "Script URL" that appears when you select "Custom install script". If you put the URL of a page and then click "Fetch URL", the control panel will fetch this page, parse it and look for an install script.

This means that if you put your script available on the web, all you have to do to let people use it is give them a link to the URL https://panel.webfaction.com/app/create?script_url=<URL where the script is> (don't forget to escape the URL where the script is).

This is what's being done on this page, where people can install Joomla or MoinMoin by just clicking the "Install" link.

Finally, in order for the control panel to find your script on your page, your script must be enclosed between two magic tags which are:

-----BEGIN WEBFACTION INSTALL SCRIPT----- -----END WEBFACTION INSTALL SCRIPT-----

7 comments:

---

This is great! I was looking forward to it.

And thanks for the moinmoin script had on my todo list installing a test one, guess I can take care of that now.

I'm going to write a drupal install script in the following days to testdrive the API.

ones again thanks!

---

This looks really nice! Really nice how you guys are innovating in the web-hosting field. Keep up the good work!

I will for sure do a script for Skeletonz (http://orangoo.com/skeletonz/).

---

Very good site. You are doing a great job. Please keep it up!

---

This look like a very nice feature to have! (I yet have to try it when I move to webfaction this week) Certainly innovative.

What other things are available using this api? (or any other python-able way)

---

Oh, by the way, I sent a question via the Contact form and I received a reply. Is the address from which it came real? I mean, I replied to it, but I'm not sure if it will reach Remi Delon (who responded me) or the guys at webfaction...

I will use the contact form anyways to ask my new questions if I don't receive a reply in a couple of days, but I just wanted to be sure. (I don't like waiting for something, and then realizing I had to do it other way :)

---

Hello Andres,

> What other things are available using this api? (or any other python-able way)

There are a number of API functions. I've started documenting them but the process is far from complete:

> Oh, by the way, I sent a question via the Contact form and I received a reply. Is the address from which it came real? I mean, I replied to it, but I'm not sure if it will reach Remi Delon (who responded me) or the guys at webfaction...

http://wf.davidsissitka.com/api/reference/

Remi Delon is one of the owners of WebFaction. :)

---

It seems the 'machine' paramater is required but it isn't mentioned here.

install_script create|delete username password MACHINE app_name autostart extra_info

What do we need to use for 'machine'?

---

Leave a new comment:

(Note: comments may be moderated)

Author:
Email (not displayed):
Website:
Message: