XML API PHP Class version 1.0

[cPanelDavidN]

To my knowledge, there isn't a method to install system level applications, such as PEAR, via the APIs. The only thing that would come close would be the Fileman module, which is used for file system manipulation, typically within a user's home directory. But I think IF you got something feasible out of that, it's be more work than it's worth...at that point, raw scripting would serve you better.

Regards,
-DavidN

[websitedesigner]

Hi guys sorry to kind of double post but I wasn't sure if this should be in this thread or the main developer Discussion. I posted a new thread about an issue I was having returning cPanel account disk space and bandwidth from a server other than the one that the script was on. Here is the link http://forums.cpanel.net/f42/api-access-different-server-crashing-160497.html#post672725 any help is much appreciated.

[sclg]

I'm obviously doing something silly but I'd welcome some advice...

Say I want to set a forwarder for freddy@kin.org to go to an external email, say fred@amb.org

(I know I can connect to cPanel ok as a call to listforwards works ok.)

The code is

$source_email = "freddy";
$dest_email =  urlencode("fred@amb.org");

$xmlapi = new xmlapi($ip);
$xmlapi->set_port("2082");
$xmlapi->password_auth($user,$root_pass);
$xmlapi->set_output("json");

$xmlapi->set_debug(1);

print $xmlapi->api2_query($account, "Email", "addforward", array(domain=>"kin.org", email=>$source_email, fwdopt=>"fwd", fwdemail=>$dest_email) );

Looks ok to me but it returns

(Warning: fred%40amb.org does not refer to a valid local email account.)

... which is true but so what!!

What have I missed please??

Thanks
Steve

[cPanelDavidN]

Hi Steve,

The xmlapi class will URL encode your parameters for you, so on line 2 of your sample code you can simply provide the literal email string:

$source_email = "freddy";
$dest_email =  "fred@amb.org"; // NOT urlencode("fred@amb.org");

Regards,
-DavidN

[sclg]

Brilliant - thanks.

How does one go about deleting a forwarder - I couldn't see a function to do that??

Steve

[cPanelDavidN]

to delete a forward, you'll need to make an API1 call
ApiEmail < ApiDocs/Api1 < TWiki

// do setup...

// make API1 call
$xmlapi->api1_query($user, 'Email','delforward', array('email_fake@test.com=box_i_check@personal.net') );

[sclg]

Great - thanks
Steve

[virals2583]

api1 api calls do not take associative arrays, rather they take ordered parameters. you will need to pass these in the order that they appear within the api docs. f.ex:

$xmlapi->api1_query($cpuser, "Mysql", "adddb", array($newdb) );
$xmlapi->api1_query($cpuser, "Mysql", "adduser", array( $newuser, $newpass ) );
$xmlapi->api1_query($cpuser, "Mysql", "addusertodb" array($newdb, $newuser, 'SELECT INSERT UPDATE DELETE'  )); 

I am trying to use the above code but it is not working nor showing any error message. Can you please list down the proper stets how to create mysql database, user and attache use to that database?

Thanks for your help. Below code i am using.


$xmlapi = new xmlapi($ip);
$xmlapi->password_auth('root','root');

$xmlapi->set_debug(1);

$newdb = "newdatabase";
$newuser = "user";
$newpass = "password";

$xmlapi->api1_query($cpuser, "Mysql", "adddb", array($newdb) );
$xmlapi->api1_query($cpuser, "Mysql", "adduser", array( $newuser, $newpass ) );
$xmlapi->api1_query($cpuser, "Mysql", "addusertodb", array($newdb,$newuser,'SELECT INSERT UPDATE DELETE'));

Thank you
Viral Shah

[MattDees]

I am trying to use the above code but it is not working nor showing any error message. Can you please list down the proper stets how to create mysql database, user and attache use to that database?

Thanks for your help. Below code i am using.


$xmlapi = new xmlapi($ip);
$xmlapi->password_auth('root','root');

$xmlapi->set_debug(1);

$newdb = "newdatabase";
$newuser = "user";
$newpass = "password";

$xmlapi->api1_query($cpuser, "Mysql", "adddb", array($newdb) );
$xmlapi->api1_query($cpuser, "Mysql", "adduser", array( $newuser, $newpass ) );
$xmlapi->api1_query($cpuser, "Mysql", "addusertodb", array($newdb,$newuser,'SELECT INSERT UPDATE DELETE'));

Thank you
Viral Shah

Anything come up in the error log after doing this?

[cPanelDavidN]

Hi Viral

1) Those call will not return any useful information because they are API1 calls. API1 with return a 'status' and 'statusmgs' but they usually refer to the execution of cPanel and not the success of the functionality that you're invoking.

2) The third method should be "adduserdb" and NOT "addusertodb".

3) /usr/local/cpanel/logs/error_log should contain messages on the function errors.

4) On most cPanel systems, when you create a database or database user with API1 calls, the resulting resources are prefixed with your $cpuser name. Therefore, when you which to make the relationship, you must provide the literal names as they exist in MySQL.

Ex:

$cpuser = "dave"; //my cpanel account name
$newdb = "newdatabase";  
$newuser = "user";
$newpass = "password";

// create a database //
// if successful, then $cpuser with have a database 'dave_newdatabase' //
//   if $cpuser_$newdb is longer that 64 characters, it will truncate //

$xmlapi->api1_query($cpuser, "Mysql", "adddb", array($newdb) );


// create a virtual database user //
// if successful, it will act just like adding a database, it 
//   will prefix with "$cpuser_"
//   if $cpuser_$newuser is longer that 16 characters, it will truncate //

$xmlapi->api1_query($cpuser, "Mysql", "adduser", 
          array( $newuser, $newpass ) 
          );


/**
* At this point, the cPanel user "dave" has a database named 
*  "dave_newdatabase" and a virtual database user named
*  "dave_user".
*/

// create the relationship between virtual user and database //
//  The "adduserdb" function should be passed the literal resource
//   names, like 'dave_newdatabase' and 'dave_user'.  
//  On cPanel version 11.25.0 and earlier, I *think* you can get
//   away with just passing variable without a prefix, however,
//   in 11.25.1 (aka 11.28) and later, you are required to pass
//   the literal name.

$literaldb = $cpuser . '_' . $newdb;
$literaluser = $cpuser . '_' . $newuser;

$xmlapi->api1_query($cpuser, "Mysql", "adduserdb",
         array($literaldb,$literaluser,'SELECT INSERT UPDATE DELETE')
         );

Regards,
-DavidN

PS. you may wish to look at a blog post I made awhile back. It's concerning using the postwwwacct script to automatically generate MySQL databases and database users. I go into great length about properly making database API calls and have sample scripts using the xml-api PHP client class.

[kjg]

Thanks for the class. It saved us loads of work today. First time I used it and it was really easy to use, well documented and with great forum support that gave us the answers we were looking for.

Thanks

[virals2583]

Here are the error messages I am getting. I guess it is permission issue, can you tell me how to give such permissions??

[07-Aug-2010 00:54:52] URL: https://mps.legitdesigns.com:2087/xml-api/cpanel
[07-Aug-2010 00:54:52] DATA: user=mps&cpanel_xmlapi_module=Mysql&cpanel_xmlapi_func=adddb&cpanel_xmlapi_apiversion=1&arg-0=mps_newdatabase
[07-Aug-2010 00:54:52] Authentication Header: Authorization: Basic bXBzOnZpcmFs



[07-Aug-2010 00:54:52] RESPONSE:
<cpanelresult>
<data>
<result>0</result>
<reason>Access denied</reason>
</data>
</cpanelresult>

[07-Aug-2010 00:54:52] SimpleXML var_dump:
SimpleXMLElement Object
(
[data] => SimpleXMLElement Object
(
[result] => 0
[reason] => Access denied
)

)

[07-Aug-2010 00:56:16] URL: https://mps.legitdesigns.com:2087/xml-api/cpanel
[07-Aug-2010 00:56:16] DATA: user=mps&cpanel_xmlapi_module=Mysql&cpanel_xmlapi_func=adddb&cpanel_xmlapi_apiversion=1&arg-0=newdatabase
[07-Aug-2010 00:56:16] Authentication Header: Authorization: Basic bXBzOnZpcmFs



[07-Aug-2010 00:56:16] RESPONSE:
<cpanelresult>
<data>
<result>0</result>
<reason>Access denied</reason>
</data>
</cpanelresult>

[07-Aug-2010 00:56:16] SimpleXML var_dump:
SimpleXMLElement Object
(
[data] => SimpleXMLElement Object
(
[result] => 0
[reason] => Access denied
)

)

Hi Viral

1) Those call will not return any useful information because they are API1 calls. API1 with return a 'status' and 'statusmgs' but they usually refer to the execution of cPanel and not the success of the functionality that you're invoking.

2) The third method should be "adduserdb" and NOT "addusertodb".

3) /usr/local/cpanel/logs/error_log should contain messages on the function errors.

4) On most cPanel systems, when you create a database or database user with API1 calls, the resulting resources are prefixed with your $cpuser name. Therefore, when you which to make the relationship, you must provide the literal names as they exist in MySQL.

Ex:

$cpuser = "dave"; //my cpanel account name
$newdb = "newdatabase";  
$newuser = "user";
$newpass = "password";

// create a database //
// if successful, then $cpuser with have a database 'dave_newdatabase' //
//   if $cpuser_$newdb is longer that 64 characters, it will truncate //

$xmlapi->api1_query($cpuser, "Mysql", "adddb", array($newdb) );


// create a virtual database user //
// if successful, it will act just like adding a database, it 
//   will prefix with "$cpuser_"
//   if $cpuser_$newuser is longer that 16 characters, it will truncate //

$xmlapi->api1_query($cpuser, "Mysql", "adduser", 
          array( $newuser, $newpass ) 
          );


/**
* At this point, the cPanel user "dave" has a database named 
*  "dave_newdatabase" and a virtual database user named
*  "dave_user".
*/

// create the relationship between virtual user and database //
//  The "adduserdb" function should be passed the literal resource
//   names, like 'dave_newdatabase' and 'dave_user'.  
//  On cPanel version 11.25.0 and earlier, I *think* you can get
//   away with just passing variable without a prefix, however,
//   in 11.25.1 (aka 11.28) and later, you are required to pass
//   the literal name.

$literaldb = $cpuser . '_' . $newdb;
$literaluser = $cpuser . '_' . $newuser;

$xmlapi->api1_query($cpuser, "Mysql", "adduserdb",
         array($literaldb,$literaluser,'SELECT INSERT UPDATE DELETE')
         );

Regards,
-DavidN

PS. you may wish to look at a blog post I made awhile back. It's concerning using the postwwwacct script to automatically generate MySQL databases and database users. I go into great length about properly making database API calls and have sample scripts using the xml-api PHP client class.

[anand]

Is there a way i can get a list of all databases and their backups for a list of users using the API ? Even if i get the list of their db's, i can manually call mysqldump to take backups. But if both can be done, it would be nothing like it.

[cPanelDavidN]

Viral,
If you are authenticating as root or a reseller into the main server address on port 2087 or 2086, it should work. If you are authenticating as the user (in your case "mps"), then you will want to use the cPanel ports 2083 or 2082; just like normal browser usage.

I noticed your server address is a subdomain. Do you normally log into WHM at that specific address?

You can test API requests in a browser too, after you've authenticated; your browser will keep you authenticated:

1)log into WHM on port 2087
2) then change the URL to https://$server:2087/xml-api/version or https://$server:2087/xml-api/applist to get some basic output and verify that things are working.
3) make any request in the URL address bar

-David

[cPanelDavidN]

Hi anand,

What you describe would be multiple calls and you'd have to introduce your own logic to merge the information.

You'll probably want to take a look at these functions in the API2 MysqlFE module:
ApiMysqlFE < ApiDocs/Api2 < TWiki

and maybe this these too:
API2
ApiFileman < ApiDocs/Api2 < TWiki
ApiBackups < ApiDocs/Api2 < TWiki

API1
ApiFileman < ApiDocs/Api1 < TWiki

Simple example of API2:

// ...setup xmlapi object ... //

$list_of_users = array('tom','dick','harry');

$args = array(); // there are none for this request
$module = 'MysqlFE';
$function = 'listdbdbackup';

$results = array();

foreach ($list_of_users as $cpuser){
    $results[$cpuser] = $xmlapi->api2_query($cpuser, $module, $function, $args);
}

// ... do something with results array... //

Regards,
-David