Note
You are viewing the documentation for an older release of Interworx (6.x). To see documentation for the current generally available release of Interworx, click here: 7.13.
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¶
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 = array( 'email' => '[email protected]',
'password' => 'nodeworxpass');
Alternatively if we are authenticating with the SiteWorx API, we will need to specify a domain.
$key = array( '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.
<?php
// NodeWorx
$key =
'-----BEGIN INTERWORX API KEY-----
...
-----END INTERWORX API KEY-----';
// SiteWorx
$key =
array( 'domain' => %%YOURDOMAIN%%,
'apikey' => '-----BEGIN INTERWORX API KEY-----.....' );
Examples API call using XMLRPC and SOAP, in PHP¶
$key = array( 'email' => '[email protected]',
'password' => 'nodeworxpass' );
$api_controller = '/nodeworx/users';
$action = 'add';
// Be aware that even actions that require no input still require the parameter
// Just pass in an empty array
$input = array( 'nickname' => 'Example User',
'email' => '[email protected]',
'language' => 'en-us',
'theme' => 'interworx',
'password' => 'pass',
'confirm_password' => 'pass',
'perms' => array( 'LOGIN', 'SWACCOUNTS' ) );
$params = array( 'apikey' => $key,
'ctrl_name' => $api_controller,
'action' => $action,
'input' => $input );
// You can connect using XMLRPC, like this:
// NOTE: You'll need to have included the Zend Framework to do this
$client = new Zend_XmlRpc_Client( 'https://%%SERVERNAME%%:2443/xmlrpc' );
$result = $client->call( 'iworx.route', $params );
// Or, you can use SOAP, like this:
// NOTE: if SOAP is missing, try 'yum install php-soap'
$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};
}
Warning
We are still working on getting our API documentation organized on the
subsequent pages, so some things may not appear as expected in tables, etc.
In the meantime, feel free to use the PDF version of this documentation for reference.