API

Introduction

The InterWorx API is a fantastic resource for developers to easily and rapidly achieve integration of InterWorx into their own products. The InterWorx API also allows the technically savvy webhost to automate custom tasks that might otherwise be too difficult or cumbersome to perform manually. It allows complete and total control over almost every aspect that a user would have access to if they were performing the actions themselves through the web interface. It is capable of feeding the same information that a user would see inside the control panel to your own application. The main reason that the API is so robust is that the NodeWorx and SiteWorx web interfaces are API clients themselves - InterWorx operates as an abstracted application model behind the API. That means all new features are added to the API first before they are even accessible in the web interface and that means you will rarely have to wait for something that you can do in the interface to become available in the API.

The API is based on open standards known collectively as “Web Services,” which include XMLRPC, SOAP, and the Web Services Definition Language (WSDL). These standards are supported by a wide range of development tools on a variety of platforms. Since the API requests and responses in the InterWorx API follow current standards, any programming language with the appropriate library support can be used.

Note

SOAP WSDL Point of Contact: https://%%SERVERNAME%%:2443/soap?wsdl XMLRPC Point of Contact: https://%%SERVERNAME%%:2443/xmlrpc Where %%SERVERNAME%% is the IP or Hostname of the InterWorx server.

The Two API’s

The API is divided into 2 parts just like panel. There is the NodeWorx API which allows you to perform server administration tasks and manage resellers or SiteWorx accounts just like you would in NodeWorx and there’s also a SiteWorx API which pertains to a specific SiteWorx acccount and allows you to perform tasks related to that SiteWorx account. For example to edit a SiteWorx account’s usage quota you’d use the NodeWorx API but to add a new e-mail account you’d use the SiteWorx API.

Authentication

There are three ways to authenticate with the API. The easiest way is to use the e-mail and password of a NodeWorx user and you will be able to perform the actions that the user is permitted to make. You can also use the reseller’s NodeWorx API key. The reseller system is explained in more detail in the Reseller System Guide. This is often preferred because often users lose or change their passwords which would break integration. The API key, on the other hand, will only change if perhaps it is compromised or the NodeWorx reseller wants to discontinue allowing access to a 3rd party application. Lastly, you can use the session ID which might be preferable in instances where the user clicks a button in a plugin and their session ID is passed to your application to provide temporary access to their panel’s functions.

The one thing to remember, though, is when using the SiteWorx API, you must specify a domain to work on or the API won’t know which SiteWorx account you are referring to.

Using the API

The API requires four parts.

  1. Authentication: See the section above regarding this information.

  2. Controller: The API controller the call should be directed to. A list of NodeWorx and SiteWorx controllers can be found on their respective pages, linked at the bottom of this document. These should be expressed just as they are shown on those pages. For example /nodeworx/dns or /siteworx/dns.

  3. Action: The action to complete. This is usually a specific task related to the controller. For example: adding an email box uses the add action in the controller /siteworx/email/box.

  4. Input Parameters: An array of parameters necessary to complete the action. Some actions to multiple fields (for example: adding a mailbox would require a username, password, and confirm_password as a minimum) and others require no input parameters.

    Warning

    Even when the action being called requires no parameters, it is still necessary to define the input parameter itself. Simply initialize the parameter as an empty array.

PHP Example Usage

The first thing we need to worry about is creating our authentication array object. As stated in the overview, we have 3 options: Username and Password combo, API key, and session ID.

Authenticating via Username and Password

For the username and password, we just need create an associative array with email and password as keys for a NodeWorx API login.

$key = [
    'email'   => '[email protected]',
    'password' => 'nodeworxpass'
];

Alternatively if we are authenticating with the SiteWorx API, we will need to specify a domain.

$key = [
    'email'    => '[email protected]',
    'password' => 'siteworxpass',
    'domain'   => 'example.com'
];

This is one of the more basic ways to log in. The caveat is that if the user’s password is changed, your code will stop being able to authenticate with the API.

Authenticating via an API key

Each reseller account can create an API key as well, and use that to login, rather than use the e-mail/password combination.

NodeWorx API Key Authentication:

$key =
'-----BEGIN INTERWORX API KEY-----
...
-----END INTERWORX API KEY-----';

SiteWorx API Key Authentication:

$key = [
    'domain' => %%YOURDOMAIN%%,
    'apikey' => '-----BEGIN INTERWORX API KEY-----.....'
];

Examples API call using XMLRPC and SOAP, in PHP

$key = [
    'email'    => '[email protected]',
    'password' => 'nodeworxpass'
];

$api_controller = '/nodeworx/users';
$action         = 'add';

$input = [
    'nickname'         => 'Example User',
    'email'            => '[email protected]',
    'language'         => 'en-us',
    'theme'            => 'interworx',
    'password'         => 'pass',
    'confirm_password' => 'pass',
    'perms'            => ['LOGIN', 'SWACCOUNTS']
];

$params = [
    'apikey'    => $key,
    'ctrl_name' => $api_controller,
    'action'    => $action,
    'input'     => $input
];

Connect using XMLRPC via the Laminas Framework:

$client = new Laminas\XmlRpc\Client( 'https://%%SERVERNAME%%:2443/xmlrpc' );
$result = $client->call( 'iworx.route', $params );

Connect using SOAP (after installing the php-soap package):

$client = new SoapClient( 'https://%%SERVERNAME%%:2443/soap?wsdl' );
$result = $client->route( $key, $api_controller, $action, $input );

Perl Example Usage

#!/usr/bin/perl -w

#You must install the RPC::XML perl module.
require RPC::XML;
require RPC::XML::Client;

# This is the connection to the XMLRPC service to communicate with the API
$cli = RPC::XML::Client->new('https://%%SERVERNAME%%:2443/xmlrpc');

#This is the API key stuct, pass authentication information here.
$apikey = RPC::XML::struct->new({
    'email' =>  RPC::XML::string->new('[email protected]'),
    'password' => RPC::XML::string->new('yourpassword'),
    'domain' =>RPC::XML::string->new('%%YOURDOMAIN%%')
                             });

#This is the API controller
$ctrl_name = RPC::XML::string->new('/siteworx/email/alias');

#This is the API Action
$action = RPC::XML::string->new('add');

#This is how you pass the input, in a struct.
$input = RPC::XML::struct->new({
    'username' =>  RPC::XML::string->new('example'),
    'forwardsto' => RPC::XML::string->new('[email protected]')
                            });

#This generates a pointer to an RPC::XML::struct object, which contains
#  the API's output
#Be aware that even actions that require no input still require the parameter
#Just pass in an empty array
my $resp = $cli->send_request('iworx.route',
                           $apikey,
                           $ctrl_name,
                           $action,
                           $input);

#value() gives a pointer to a native PERL hash table. This will contain
#  the "status" and "payload" keys if the XMLRPC communication with the
#  API was successful. If there was a problem and you sent bad data to
#  the API, they keys will be "faultString" and "faultCode". You may
#  want to do some error checking here.
my $results = $resp->value();

#This assumes that we communicated properly with the API, and got a valid
#response from it.
#We check the key "status". If it's 0, the add alias worked out!
if ($results->{status} == 0){
    print "Success!\n";

} else {
    print "Failure!\n";
}

#This is here to print out the payload. The payload can be delivered in an
#array or as a string, depending which controller/action you are using.
if (ref($results->{payload}) eq 'ARRAY') {
    print "Payload is an array.\n";
    my @payload = @{$results->{payload}};
    foreach (@payload)
    {
     my @key = @{$_};
     print "@key" . "\n";
    }
} else {
    print "Payload is a string.\n";
    print $results->{payload};
}

Golang Example Usage

package main

import (
     "fmt"
     "github.com/kolo/xmlrpc"
)

type RouteResponse struct {
     ReplyCode interface{} `xmlrpc:"reply_code"`
     Payload   interface{} `xmlrpc:"payload"`
     Status    interface{} `xmlrpc:"status"`
}

func main() {
     url := "https://%%YOURSERVERNAME%%:2443/xmlrpc"

     key := `-----BEGIN INTERWORX API KEY-----
     -----END INTERWORX API KEY-----`

     apiController := "/nodeworx/users"
     action := "add"

     callInput := map[string]any{}

     callInput["nickname"] = "Example User"
     callInput["email"] = "[email protected]"
     callInput["language"] = "en-us"
     callInput["theme"] = "interworx"
     callInput["password"] = "pass"
     callInput["confirm_password"] = "pass"

     var perms []string
     perms = append(perms, "LOGIN")
     perms = append(perms, "SWACCOUNTS")

     callInput["perms"] = perms

     params := []any{
             key,
             apiController,
             action,
             callInput,
     }

     client, err := xmlrpc.NewClient(url, nil)
     if err != nil {
             fmt.Println("Error creating XML-RPC client:", err)
             return
     }

     var response RouteResponse
     err = client.Call("iworx.route", params, &response)
     if err != nil {
             fmt.Println("Error in XML-RPC call:", err)
             return
     }
}

Python Example Usage

import xmlrpc.client

key = """-----BEGIN INTERWORX API KEY-----
    -----END INTERWORX API KEY-----"""

controller = "/nodeworx/users"
action = "add"
input = {
    'nickname': 'Example User',
    'email': '[email protected]',
    'language': 'en-us',
    'theme': 'interworx',
    'password': 'pass',
    'confirm_password': 'pass',
    'perms': ['LOGIN', 'SWACCOUNTS']
}

client = xmlrpc.client.ServerProxy('https://%%SERVERNAME%%:2443/xmlrpc')
response = client.iworx.route(key, controller, action, input)