Accessing WebFaction's API with Java.
31.03.2018

WebFaction (yes, it is an affiliate link) is a pretty neat and realiable hosting provider – they call 'Hosting for developers' themselves. I am stuck almost 10 years with them and never had to complain. They're also providing API and that's what we'll talk today.

My motivation is clear – I am hosting some of the Java applications deployed on Tomee application server and just recently I had to implement simple control panel for administrating e-mail addresses and mailboxes. Fortunatelly, there is an API for that purpose available on WebFaction. As I said, my applications are in Java, so it make sense to implement administration in Java too.

Prerequisities.

Of course, you'll have to have WebFaction account :). And I suppose you know name and password for your account. Then you need to know capitalized name of server. For example, if your server is 'web585.webfaction.com', capitalized name would be 'Web585'. You can get server address in WebFaction Control Panel.

I am using Maven for maintaining my projects and their dependencies. If you are using different tooling (like Gradle), you have to adapt the configuration (shouldn't be hard) or manually copy necessary libraries into CLASSPATH. Webfaction API is using XML-RPC protocol for communication, therefore we'll add dependecies into pom.xml file:

    <dependency>
        <groupId>org.apache.xmlrpc</groupId>
        <artifactId>xmlrpc-client</artifactId>
        <version>3.1.3</version>
    </dependency>
    <dependency>
        <groupId>org.apache.xmlrpc</groupId>
        <artifactId>xmlrpc-common</artifactId>
        <version>3.1.3</version>
    </dependency>

Now we have necessary library support. For those not using automatic dependency system (like Maven), libraries can be obtained at Downloading Apache XML-RPC.

Start of communication, authentication.

Before we can call API request, we need to get authenticated and get session ID. You can refer to Logging in section of original documentation for more details. Simply said, we need session ID for any call to the API (with login exception)

First we'll prepare method for getting XmlRpcClient instance, which is needed for all API calls:

    private XmlRpcClient getXmlRpcClient() throws MalformedURLException {
        XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
        config.setServerURL(new URL("https://api.webfaction.com/"));
        XmlRpcClient client = new XmlRpcClient();
        client.setConfig(config);
        return client;
    }

For getting session ID, we'll create following method:

    public String getSessionId(String userName, String password, String capitalizedServer) {
        try {
            XmlRpcClient client = getXmlRpcClient();
            Object[] params = new Object[]{userName, password, capitalizedServer};
            Object[] result = (Object[]) client.execute("login", params);
            return (String) result[0];
        } catch (MalformedURLException | XmlRpcException e) {
            // handle exception here
        }
    }

We are creating array of parameters Object[] params for the call and as a result we got another array. At index 0, there is session ID we are interested in.

Calling API.

As far as we are authenticated, we can make any API call. Let's take for example changing mailbox password:

    public void changePassword(String sessionId, String mailbox, String password) {
        try {
            XmlRpcClient client = getXmlRpcClient();
            Object[] params = new Object[]{sessionId, mailbox, password};
            client.execute("change_mailbox_password", params);
        } catch (MalformedURLException | XmlRpcException e) {
            // handle exception here
        }
    }

In my opinion, thing is pretty straightforward. Similarly, you can call any API function. Common procedure is like:

1. Get XmlRpcClient instance.
2. Prepare Object[] params parameters (with session ID mandatory).
3. Execute call.
4. Handle result (if any).

Well, that's it. I hope, I made someone happy :). If you have any problem regarding topic, feel free to contact me – I'll try to help.