API2 Basics?

[mikelegg]

I've had a little experience coding with the old cPanel Accounting Module in PHP, but I'd like to start using the new API2.

I've browsed through the docs at http://www.cpanel.net/plugins/api2/index.html

But I can't find anything that spells out how to actually use the API2 Tags in a real-world situation.

Can anyone point me in the right direction?

[mikelegg]

Looking through the forums it appears that I'm not the first person to ask this question.

So I'll try to work this out and post my results here for the benefit of everyone who has asked.

The first things I've noticed are.

1) Be careful of what you find via Google searches because most of it deals with the old cPanel Accounting module.
2) The secret to using the cPanel API2 tags in PHP seems to be Curl. I'll try and post some sample code when I work out how to do it.

[mikelegg]

I'm getting nowhere fast. I've gathered a few cryptic clues from varous forum posts but I can find no clear explanation of how to implement the API in an actual script.

I think https://userass@server:2086/xml-api/applist should return all available XML API functions from the cPanel server, but it doesn't return anything for me.

Can anyone give me a couple more clues as to how to do this?

[cPanelDavidG]

Originally Posted by mikelegg

I'm getting nowhere fast. I've gathered a few cryptic clues from varous forum posts but I can find no clear explanation of how to implement the API in an actual script.

I think https://userass@server:2086/xml-api/applist should return all available XML API functions from the cPanel server, but it doesn't return anything for me.

Can anyone give me a couple more clues as to how to do this?

The XML API (not API2 directly) can be accessed by logging into WHM and then entering specific URLs.

Try logging into WHM and then going to https://server:2087/xml-api/applist or http://server:2086/xml-api/applist

Do you see any XML output now?

[mikelegg]

Originally Posted by cPanelDavidG

The XML API (not API2 directly) can be accessed by logging into WHM and then entering specific URLs.

Try logging into WHM and then going to https://server:2087/xml-api/applist or http://server:2086/xml-api/applist

Do you see any XML output now?

Thanks David

I was trying to run it from another server, not the server itself.

If I log into WHM and paste the link into the address bar, I can get it to return the app list, but it prompts me to log in again.

What I really want to do is access the details of remote servers, not the local one- is there a way to do this?

[cPanelDavidG]

Originally Posted by mikelegg

Thanks David

I was trying to use run it from another server, not the server itself.

If I log into WHM and paste the link into the address bar, I can get it to return the app list, but it prompts me to log in again.

What I really want to do is access the details of remote servers, not the local one- is there a way to do this?

Sure, here's a simplistic PHP script that demonstrates how you can connect to a remote server to execute API calls.

PHP Code:

// VARIABLES:
//   $hash = your hash (not needed if using password authentication)
//   $user = username for the reseller accompanying that hash
//   $pass = password for that reseller (not needed if using hash authentication)
//   $theServer = your server's hostname or IP

# What is the path to the API function you wish to use?
$apiPath = '/xml-api/gethostname';

// NOTE:
//    THIS CODE WILL ONLY WORK IF YOU HAVE ENABLED
//    OPENSSL IN PHP.  YOU CAN DO THIS BY GOING TO WHM
//    AND IN THE SOFTWARE SECTION, CLICK ON APACHE UPDATE
//    THEN LOAD PREVIOUS CONFIG AND THEN CHECK THE BOX
//    NEXT TO OPENSSL TO ENABLE SSL SUPPORT
//
// Of course, you could always go with http:// and 2086, but why?

# Make hash into one long string, in case it isn't already
$hash = str_replace("\n",'',$hash); // Note \r is not part of the newline indicator on *nix systems.

# Open a socket for HTTPS
$fp = fsockopen('ssl://' . $theServer, 2087, $errno, $errstr, 30);

# Uncomment to use unsecure HTTP instead
//$fp = fsockopen($theServer, 2086, $errno, $errstr, 30);

# Die on error initializing socket
if ($errno == 0 && $fp == FALSE) {
 die('Socket Error: Could not initialize socket.');
} elseif ($fp == FALSE) {
 die('Socket Error #' . $errno . ': ' . $errstr);
}

# Assemble the header to send
$header = '';
$header .= 'GET ' . $apiPath . " HTTP/1.0\r\n";
$header .= 'Host: ' . $theServer . "\r\n";
$header .= "Connection: Close\r\n";
$header .= 'Authorization: WHM ' . $user . ':' . $hash . "\r\n";
# Comment above line and uncomment below line to use password authentication in place of hash authentication
//$header .= 'Authorization: Basic ' . base64_encode($user . ':' . $pass) . "\r\n";
$header .= "\r\n";

# Send the Header
fputs($fp, $header);

# Get the raw output from the server
$rawResult = '';
while (!feof($fp)) {
 $rawResult .= @fgets($fp, 128); // Suppress errors with @
}

# Close the socket
fclose($fp);

# Ignore headers
$rawResultParts = explode("\r\n\r\n",$rawResult);
$result = $rawResultParts[1];

# Output XML
echo $result; 


With minimal knowledge of PHP, you can customize this code to make API calls to multiple servers. Just remember that access hashes are typically unique to each account on each server.

You will need reseller access or better on those remote servers to be able to use the APIs on those servers. Also note, you can't do anything via the API that you wouldn't be able to do via the WHM interface with the same credentials.

[mikelegg]

Thanks David

Now I've got some idea of how it all works - it's not unlike using the old cPanel Accounting functions.

I'll generally be logging in as root so I should be able to access all domains on the servers.

[mikelegg]

One more question ... what syntax is used to specify an API2 path?

I've used /xml-api/listaccts to build an array of domains, now I'd like to use
Email::listmaildomains to get all parked and addon domains that have mail addresses on the account.

The sample code in the documentation is ...

<?cp Email::listmaildomains( %, domain) skipmain=1 ?>

But obviously that syntax won't work in PHP.

I think it's something like'/xml-api/cpanel?listmaildomains&domain='. $domain .'&skipmain=1', but that's not working for me at present.

I've also tried '/xml-api/cpanel?user=root&xmlin=<cpanelaction><module>Email </module><apiversion>2</apiversion><func>listmaildomains</func><args><domain>'. $domain .'</domain></args></cpanelaction>'
But it doesn't return anything.

[cPanelDavidG]

The space after Email in:

...<cpanelaction><module>Email </module>...

is a likely cause of no data being returned.

[mikelegg]

Originally Posted by cPanelDavidG

The space after Email in:

...<cpanelaction><module>Email </module>...

is a likely cause of no data being returned.

The space isn't in my code, it just appears in the post after I save it.

If I edit the post it doesn't appear, so I can't remove it.

[cPanelDavidG]

Originally Posted by mikelegg

The space isn't in my code, it just appears in the post after I save it.

If I edit the post it doesn't appear, so I can't remove it.

What's your full cPanel/WHM version information?

[mikelegg]

Originally Posted by cPanelDavidG

What's your full cPanel/WHM version information?

cPanel 11.24.2-C32034 - WHM 11.24.2 - X 3.9

[cPanelDavidG]

Originally Posted by mikelegg

cPanel 11.24.2-C32034 - WHM 11.24.2 - X 3.9

Okay.

You mention that nothing is being returned. So if not even an error message is being returned, are you sure the connection to the server is properly established?

[mikelegg]

Originally Posted by cPanelDavidG

Okay.

You mention that nothing is being returned. So if not even an error message is being returned, are you sure the connection to the server is properly established?

The connection is working because what I'm doing is creating an array of domains using /xml-api/listaccts (which is working fine).

Then I'm looping through the array of domains and executing /xml-api/cpanel?user=titan&xmlin=<cpanelaction><module>Emai l</module><apiversion>2</apiversion><func>listmaildomains</func><args><domain>'. $domain .'</domain></args></cpanelaction> for each domain in the array.

It's only this second call that's not returning anything.

I've assumed there are accounts on the server that have email addresses on secondary domains - but maybe I've assumed wrong?

[cPanelDavidG]

Originally Posted by mikelegg

The connection is working because what I'm doing is creating an array of domains using /xml-api/listaccts (which is working fine).

Then I'm looping through the array of domains and executing /xml-api/cpanel?user=titan&xmlin=<cpanelaction><module>Emai l</module><apiversion>2</apiversion><func>listmaildomains</func><args><domain>'. $domain .'</domain></args></cpanelaction> for each domain in the array.

It's only this second call that's not returning anything.

I've assumed there are accounts on the server that have email addresses on secondary domains - but maybe I've assumed wrong?

Are you also changing the username for user= to reflect the cPanel user for that domain as well in your loop?