Using API 2 Functions

For cPanel & WHM versions before 11.30

The methods explained in this document are supported; however, cPanel tags will eventually be phased out. If you plan to make your application compatible with all future versions of cPanel & WHM, you should use our LiveAPI system whenever possible.

Our API 2 is the most advanced of cPanel's APIs. It is considerably more complicated than API 1; however, it is much more flexible. You can use API 2 functions to write custom cPanel modules and create your own API 2 functions. Our API 2 system uses its own custom template system to display output. Our API 2 system also differs from API 1 as it uses named parameters, rather than ordered parameters.

API 2 Output Format

API 2 returns data structures which, generally, can be described as hashes or arrays of hashes.

In this document, we will be using XML to explain the data returned by API 2 calls. If you wish to look at this data expressed in a Data::Dumper syntax, please use the API Tracer.

When API 2 returns data via the XML API, it will enclose the data within <data> tags; for example:

<data>
  <domain>cptest.com</domain>
</data> 

For the rest of this document, we will omit the <data> node when describing this data, since it should be implied.

API 2 is only capable of displaying 2 levels of contained elements.

Calling API 2

API 2 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, API 2 uses named arguments rather than order-based arguments. For this reason, the API 2 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 API 2 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 learn how the % works to display data below.

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

Passing POST and GET Data to API 2 Functions

You can also pass POST or GET data to API 2 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 API 2 using the $FORM hash, as follows:

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

Filtering and sorting API 2 output

When calling API 2 functions, you can also access some meta-variables that allow you to:

• Filter output
• Sort output

Displaying Return Data

API 2 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 API 2 call via a <cp ?> tag. This function returns information similar to the following:

<data>
    <listid>mailinglist_domain.com</listid>
    <desthost>192.168.1.1</desthost>
    <list>mailinglist@domain.com</list>
  </data>
  <data>
    <listid>mailinglist2_domain.com</listid>
    <desthost>192.168.1.1</desthost>
    <list>mailinglist2@domain.com</list>
  </data> 

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, simply change the angled brackets to square brackets. In this particular scenario, you may want to insert a

<br />

tag between mailing lists, like so:

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

This should return:

mailinglist@domain.com
mailingist2@domain.com

(We'll learn how the % works to display data below.)

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

Symbol	Replacement Tag
:	\{colon}
,	\{comma}
]	\{leftbracket}
[	\{rightbracket}
)	\{rightparenthesis}
(	\{leftparenthesisi}
%	\{percent}

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:

<data>
  <txtdiskquota>250</_txtdiskquota>
  <diskquota>250</diskquota>
  <diskusedpercent>0</diskusedpercent>
  <diskused>0</diskused>
  <humandiskquota>250 MB</humandiskquota>
  <_diskused>0<_/diskused>
  <login>whatwhat@asdf.com</login>
  <email>whatwhat@asdf.com</email>
  <domain>asdf.com</domain>
  <user>whatwhat</user>
  <humandiskused>None</humandiskused>
  <diskusedpercent20>0</diskusedpercent20>
  <_diskquota>250</_diskquota>
</data> 

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 API 2 system will sometimes return nested containers within a document; for example:

 <dblist>
    <db>cpuser_dbname</db>
    <user>cpuser_dbname</user>
  </dblist>
  <dblist>
    <db>cpuser_dbname2</db>
    <user>cpuser_dbname</user>
  </dblist>
  <shortuser>dbuser</shortuser>
  <user>cpuser_dbuser</user> 

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

Additional Resources

• The LiveAPI System — The LiveAPI system is the latest and greatest method for accessing and running cPanel's API functions.
• API 2 modules and functions — This is a set of reference documents for API 2 modules and functions.
• XML API — You can use our XML and JSON APIs to call API 2 functions.