Chapter 1: Introduction Up Part I: InterWorx API Overview Part II: NodeWorx API Spec 

2 Using the API

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

2.1.1 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’	=> ’nodeworxlogin@example.com’,
              ’password’ => ’nodeworxpass’);
Alternatively if we are authenticating with the SiteWorx API, we will need to specify a domain.
$key = array( ’email’    => ’siteworx@siteworx.com’,
              ’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.

2.1.2 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—--.....’ );

2.1.3 Examples API call using XMLRPC and SOAP, in PHP


$key = array( 'email'    => 'nodeworxlogin@example.com',

              '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'            => 'exampleuser@example.com',

                '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 );

2.2 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('siteworx@siteworx.com'),

    '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('someone@somewhere.com')

			       });



#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};

}

 Chapter 1: Introduction Up Part I: InterWorx API Overview Part II: NodeWorx API Spec 

(C) 2017 by InterWorx LLC