Calling API2 Functions

cPanel uses the API2 system to obtain information about specific accounts. This information can be as simple as the amount of disk space an account is using, or as complex as the structure of a DNS zone file.

The API2 system can also be used for executing cPanel actions, such as creating email accounts or changing passwords.

The API2 system is the most advanced of cPanel's APIs and considerably more complicated to use than API1. The API2 system uses its own custom templating system to display output.

Note: API2 uses named parameters rather than ordered parameters.

Remember: You can create your own API2 function calls with a custom cPanel module. To learn more about cPanel modules, visit our documentation here.

API2 Output Format

API2 data is returned as an array of hashes. These hash arrays are easily expressed using Perl's Data::Dumper module. The Data::Dumper module formats information in the following way:

• { } — Indicates a hash.
• key => value — Indicates a hash key/value pair. Here, value can be either a scalar or an array of hashes.
• [ ] — Indicates an array.

The API2 system adheres to a strict output format when returning data. Hash elements must either be scalar variables or arrays of hashes. Data is not generally returned in nested hashes or arrays of scalars, as these cannot be expressed with API2's templating system.

Hash Values as Scalars

MsqlFE::listhosts is a good example of API2 output in which the hash elements are assigned to scalar variables:

{
    'uri_host' => '127.0.0.1',   # this is a URI-encoded version of the host
    'host' => '127.0.0.1'
}

Hash Value as an Array of Hashes

MysqlFE::listusers is a good example of an API2 return in which a hash element is assigned to an array of hashes. It returns a hash element named dblist which displays user-to-database maps, like so:

'dblist' => [
    {
        'db' => 'cpuser_dbname',
        'user' => 'cpuser_dbname'
    }
],
'shortuser' => 'dbuser',
'user' => 'cpuser_dbuser'

Calling API2

API2 calls are made between <?cp and ?> HTML tags. The tags contain 2 main elements:

1. A templating system, and
2. A piece of code that passes variable data to the API call.

As noted above, API2 uses named arguments rather than order-based arguments. For this reason, the API2 system offers quite a bit of flexibility in the variation of information that a single call can return.

Input parameters are passed in a way that is very similar to HTML attributes. Specifically, the tags are used in the following way:

<?cp Module::Function(
        Call Template,
        Return Variables (::Variable Template: if var is array of hashes),
        )
             Input Parameters (formatted as Parameter=”Value”)
?>

In the example above:

• Module — Represents the module that holds the function you wish to use.
  • For example: Mysql::
• Function — Represents the API2 function you wish to use.
  • For example: adddb
• Call Template — Defines how the output information is styled.
  • For more information on this value, please see our documentation below.
• Return Variables — Specifies which variable should be displayed by the function's output.
  • For more information on this value, please see our documentation below.
• Input Parameter — Represents any parameters you wish to pass to the function.
  • For example: dbname

To call the Email::addpop function, you would use a code block similar to the following:

<?cp Email::addpop( 
     %, 
     reason 
     ) 
	domain=”testdomain.com” ,
	email =”username”,
	password=”p4ssw0rd”,
	quota=”100”,
?>

We'll explain how the % works to display data in the next section.

Note: New lines are optional. The comma after the last parameter is required.

Passing POST and GET Data to API2 Functions

You can also pass POST or GET data to API2 functions by using the $FORM variable. The $FORM variable is a hash that is parsed by cpsrvd and contains all of the FORM and GET data passed to a particular page in cPanel. For example, if you want to call a page using the following POST or GET parameters:

“addpop.html?username=test&pass=testing123&domain=testdomain.com&quota=10”

you would pass them to API2 using the $FORM hash, as follows:

<?cp Email::addpop( 
     %, 
     reason 
     ) 
	domain=$FORM{‘domain’},
	email =$FORM{‘username’},
	password=$FORM{‘pass’},
	quota=$FORM{‘quota’}
?>

Displaying Return Data

API2 uses a templating system for displaying returned data. A single <?cp ?> tag can contain several different templates.

Let's use the Email::listlists function to create a simple example of an API2 call via a <cp ?> tag. This function returns information similar to the following:

[
  {
    'listid' => 'mailinglist_domain.com',
    'desthost' => '192.168.1.1',
    'list' => 'mailinglist@domain.com'
  },
 {
    'listid' => 'mailinglist2_domain.com',
    'desthost' => '192.168.1.1',
    'list' => 'mailinglist2@domain.com'
  }
];

If, for example, you wanted simply to output the list element, you would use the tags like so:

<?cp Email::listlists(
     %, 
     list,
     )
?>

The output of this function would resemble the following

mailinglist@domain.commailinglist2@domain.com

If, for display purposes, you would like to embed HTML into your call, you simply change the angled brackets to square brackets. In this particular scenario, you may want to insert a

<br />

<?cp Email::listlists(
     %[br /], 
     list,
     ) 
?>

This should return:

mailinglist@domain.com
mailingist2@domain.com

(We'll explain how the % works to display data in the next section.)

Due to the API2 system's markup language, some characters cannot be properly displayed inside of the API2 tags. If you wish to use these characters, you will need to replace them with one of the following tags:

Returning Multiple Pieces of Data

When using a <?cp ?> tag, you will generally not want to return a single piece of information.

For example, examining the Email::listpopswithdisk function, you will see that it returns quite a bit of information; however, none of this information is particularly useful on its own.

The output of the Email::listpopswithdisk function would resemble the following:

{
   'txtdiskquota' => '250',
   'diskquota' => '250',
   'diskusedpercent' => '0',
   'diskused' => '0',
   'humandiskquota' => '250 MB',
   '_diskused' => '0',
   'login' => 'whatwhat@asdf.com',
   'email' => 'whatwhat@asdf.com',
   'domain' => 'asdf.com',
   'user' => 'whatwhat',
  'humandiskused' => 'None',
  'diskusedpercent20' => '0',
  '_diskquota' => '250'
},

The percent (%) symbol, when used inside of the <?cp ?> tags, acts a placeholder for the data to be returned. The order in which variables are listed after the call template indicates which placeholder should contain which piece of information.

For example, the following function:

<?cp Email::listpopswithdisk( 
     % \{leftparenthesis} % \{rightparenthesis}[br/], 
     email, 
     humandiskquota, 
     )
?>

will display:

whatwhat@asdf.com (250MB)

Variable Templates

The API2 system can also return nested arrays of hashes within a hash. To use the system in this way, you will need to specify a separate template where the variable is defined.

Examining the data format used by the MysqlFE::listusers function will shed some light on this subject. The output returned by this function should resemble the following:

{
    'dblist' => [
      {
        'db' => 'cpuser_dbname',
        'user' => 'cpuser_dbname'
      },
      {
        ‘db’ => ‘cpuser_db2name’,
        ‘user => ‘cpuser_dbname
    ],
    'shortuser' => 'dbuser',
    'user' => 'cpuser_dbuser'
  }

In order to display this information in a useful way, you will need to define a variable template inside of the variable list. Variable templates are denoted by using a pair of colons (::) to begin and a single colon (:) to end the variable template denotation.

The keys inside of a hash can be accessed by denoting them in the following way: ${key}

Remember, key is meant to stand for the name of the key you wish to access. In this case, we'll use ${db}:

<?cp MysqlFE::listusers( 
     % has access to the following databases:[br/] %,
     user,
     dblist:: &nbsp;&nbsp;&nbsp; ${db} :,
     )
?>

The block of code above would output the following:

cpuser_dbuser has access to the following databases:
   cpuser_dbname
   cpuser_db2name

Other Uses

• API2 can also be called via the XML API. For more information on the XML API, you can visit our documentation here.