API Call Safe?

[hostb]

Hi,

I want to make use of the API for Add Addon Domain. Is the below a safe way to call the API form anywhere with in my site?
It will be called from an after hook function in my billing system. All the variables will be filled in accordingly of course.

$url = "http://$user:$pass@$domain:2082/frontend/$skin/addon/doadddomain.html?";
$url = $url . "domain=$adomain&user=$auser&pass=$apass";
$result = @file_get_contents($url);

[cPanelDavidG]

Hi,

I want to make use of the API for Add Addon Domain. Is the below a safe way to call the API form anywhere with in my site?
It will be called from an after hook function in my billing system. All the variables will be filled in accordingly of course.

$url = "http://$user:$pass@$domain:2082/frontend/$skin/addon/doadddomain.html?";
$url = $url . "domain=$adomain&user=$auser&pass=$apass";
$result = @file_get_contents($url);

That is not an API call. That's merely calling a URL in the cPanel interface to cause something to happen in a way that just happens to work for now.

If you want to use our APIs and are using PHP 5, you may want to use Matt's PHP 5 Class which is posted at:

http://forums.cpanel.net/f42/xmlapi-...ss-111897.html

Then with that PHP 5 class, you can create an addon domain by way of the following API2 function:

<?cp AddonDomain::addaddondomain('% %',result,reason) newdomain=$FORM{'domain'},dir=$FORM{'dir'},subdomain=$FORM{'user'},pass=$FORM{'pass'} ?>

When passing this into the PHP class, you will have:

Account: The cPanel account you want to execute this function as

Module: AddonDomain

Function: addaddondomain

Parameters: array( newdomain=>'the addon domain (required)'
, dir=>'Directory to serve files from starting at the user's home directory just like in cPanel (required)'
, subdomain=>'FTP username for this addon domain (required)'
, pass=>'Password for this FTP account (required)')

[hostb]

I appreciate very much your reply.

But I need a little more info. A newbie unfortunately. By background is in C.

This class seems to contain only the WHM API's.

Are you suggesting I modify it to add the cPanel calls I want to use.
ie the addaddondomain API.

[cPanelDavidG]

I appreciate very much your reply.

But I need a little more info. A newbie unfortunately. By background is in C.

This class seems to contain only the WHM API's.

Are you suggesting I modify it to add the cPanel calls I want to use.
ie the addaddondomain API.

There are many APIs when dealing with cPanel/WHM, but there are 3 main APIs - all of which are covered by the PHP class Matt made. PHP has a very similar (though much simpler) syntax to C.

WHM functions are primarily handled by the XML API. Many of these functions already have their own function calls built into the PHP class.

cPanel functions are handled by API1 and API2. None of these functions are already built into the PHP class, but the framework for calling these functions is part of the PHP class.

API1 functions look like Module="function(arguments)" whereas API2 functions look like Module::function(arguments). Keep this in mind as you move forward with possibly automating more tasks with your scripting.

Much confusion comes from the fact that you can call API1 and API2 functions via the XML API. In this case, you can just think of the XML API as being a bridge connecting your custom script that is outside the cPanel interface into the cPanel APIs.

We're using an API2 function to add an addon domain, so let's look at the example code in api2_example_withargs.php that was included with the PHP 5 class so we can get started:

include("xmlapi.php.inc");

$ip = "127.0.0.1";
$root_pass = "somepassword";

$account = "someuser";
$email_account = "someemail";
$email_domain = "somedomain.test";

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

$xmlapi->set_debug(1);
print $xmlapi->api2_query($account, "Email", "getdiskusage", array(domain=>$email_domain, login=>$email_account) ); 

The IP is the IP address of your server. You could use a hostname here, but using an IP gives you a slight performance improvement.

$root_pass stores the password you want to login to the XML API with. If you are logging in as a cPanel user, you can store the cPanel user's password in this variable.

$account is the cPanel user you want to perform this action on.

Many people use the API as a reseller or root user, but you can login as a cPanel user. So if you're not logging into the API as the root user, just replace:

$xmlapi->password_auth("root",$root_pass); 

With

$xmlapi->password_auth($account,$root_pass); 

Next, we're replacing:

 $xmlapi->api2_query($account, "Email", "getdiskusage", array(domain=>$email_domain, login=>$email_account) ); 

with your API2 function call. The first parameter is going to be the cPanel account we perform this action upon, the second parameter is the Module, third parameter the function to call and the fourth parameter is an array of input arguments for the API2 function.

In the PHP class, we used an associative array (similar to a hash table in other languages) for API2 functions and a regular (sequential) array for API1 functions. This is because arguments in API2 are named, whereas in API1 it's all based on the order in which the parameters are passed.

We are using API2, and this function takes 4 parameters as I described in my prior post.

All of this in mind, we replace the above code with:

 $xmlapi->api2_query($account, "AddonDomain", "addaddondomain", array(newdomain=>"example.com", dir="public_html/example", subdomain=>"example", pass=>"ftpPass") ); 

This will create an addon domain example.com on the account, serving content out of public_html/example with a FTP user of example with password ftpPass being created as part of this API call.

Just like in the cPanel interface, creating the FTP user/pass is required. Also, just like cPanel, you can have the addon domain serve content from anywhere within that cPanel account, just just folders within public_html.

This is admittedly a crash course in calling API2 via the PHP class that Matt has created, so if you need clarification or encounter any errors, please let me know.

[hostb]

Thanks so much.
A crash course is more than anyone could ask for.

I'll put the head down now with all this info and see what happens.

Thanks so much again.

[Gavster]

This thing is the bees knees - went through a bulk list of addon domains like a hot knife through butter.

I'm curious though - is there a list of cPanel modules, their functions, and argument lists somewhere that can be viewed online?

[cPanelMatt]

This thing is the bees knees - went through a bulk list of addon domains like a hot knife through butter.

I'm curious though - is there a list of cPanel modules, their functions, and argument lists somewhere that can be viewed online?

Well, we're still working on that, it's a work in progress, but we do have some information up:

API Reference
cPanel API2 Documentation


you can also use the API Tracer to gather information on *any* API:

Looking up cPanel API call parameters

[notionphil]

I know this thread is quite old, but I didn't see any more threads on this specific topic of the api2 adddomain call. I'm getting an error when i run the code below

$account='main';
print $xmlapi->api2_query($account, 'AddonDomain','addaddondomain', array(newdomain=>"addme.com", dir=>"public_html/addme", subdomain=>"addme", pass=>"password") );

error output:

2 Removed addme.main.com Server at line: 327. Removed Entry from httpd.conf Bind reloading on ip-173-201-xxx-xxx using rndc zone: [main.com] The subdomain, addme.main.com has been removed. 1 1 addaddondomain AddonDomain

to test it, i used an addon domain that I had not pointed to my nameservers. is that the problem? any suggestions?

Thanks,

Phil

[cPanelDavidN]

Hi Phil,

I usually see that error when trying to add a subdomain or park a domain for which the name is not registered. There's a tweak setting in WHM that can toggle this validation:

Allow unregistered domains [?]
    Allow creation of parked/addon domains that are not registered.

Regards,
-DavidN

[eternus.web]

Hello cPanel team,

I'm trying to create addon domain (which is pointed to that account) with the following function:

$rsp = $xmlapi->api2_query("user", "AddonDomain", "addaddondomain", array('newdomain'=>'new-domain.com', 'dir'=>'public_html/new-domain.com', 'subdomain'=>'new-domain', 'pass'=>'some_pass'));

print_r($rsp); 

And I'm getting the following message in array type (addon domain is not created, subdomain is not created but folder si created ):

Array
(
    [apiversion] => 2
    [data] => Array
        (
            [reason] => Deleted domain: new-domain.my-domain.com
Bind reloading on user using rndc zone: [my-domain.com]
The subdomain, new-domain.my-domain.com has been removed.
            [result] => 1
        )

    [event] => Array
        (
            [result] => 1
        )

    [func] => addaddondomain
    [module] => AddonDomain
) 

I have turned this option On: Allow unregistered domains

Can you help me please?