Application Programming Interfaces (APIs) are fundamental to the cPanel & WHM product. APIs allow developers to perform actions (functions) that source and manipulate data related to cPanel accounts and system utilities. Our APIs are used by the cPanel developers when designing new features and interfaces but are also available to 3rd-party developers. In this post, we’ll review the various APIs associated with cPanel and WHM and how you can use them in your own development.<\/p>\n
There are two APIs that affect the cPanel user space: API1 and API2<\/a>. These APIs are used throughout the cPanel interface. In fact, every cPanel interface (i.e., all themes, branding, and pages served in a descendant direct of $server\/base\/frontend\/ ) use these APIs alone to present and alter the end-user’s environment.<\/p>\n API1 and API2 each have their own set of modules*. Within each module, there is a set functions. For instance, API2’s ‘Email’ module contains a function called ‘listpopswithdisk’ that will list all the details for all of the pop email accounts associated with a cPanel username. API1 modules are listed here<\/a> and API2 modules are listed here<\/a>.<\/p>\n There are two common, false assumptions about API1 and API2 that confuse many newcomers to cPanel development. The first common misconception is that API1 begat API2. API1 and API2 are not ancestrally related. It is true that API1 was the first publicly available API in cPanel;however, development on API2 did not occur after API1. Both versions of the API were concurrently developed for several years. API1 is considered fully matured at this point in time. Active development has stopped, but API1 is maintained for bugs, security, and (as necessary) forward compatibility. The second common misconception is is that all API1 modules (and their functions) are available in API2. Sometimes, I hear the opposite, that all API2 module and functions are available in API1. Neither of these statements are true. Both API1 and API2 have their particular modules (and their functions) due, in large part, to the organic growth of the cPanel & WHM product. It is not uncommon for a module of the same name, present in both API1 and API2, to have different functions. It most cases, if a particular function exists in both API1 and API2, we recommend using API2.<\/p>\n API1 was originally designed to be a front-end-only API for use in cPanel pages. Because of this, API1 calls print their output directly to STDOUT. In various parts of the product, that output is suppressed or redirected due to the context of its usage. However, this is the exception to the rule and wouldn’t occur within a cPanel end-user interface. Since API1 was designed for use by a browsable interface, it is not out of the ordinary for an API1 function to generate a snippet of HTML**. API2, on the other hand, always returns a Perl hash structure. While this makes getting raw data much easier, it adds a layer of complexity for front end developers. (But it’s so much more flexible<\/a>! Which is why we prefer API2 functions where possible). Both API1 and API2 calls can be accessed within cPanel pages and their front end usage is described here<\/a> and here<\/a>, respectively.<\/p>\n The XML-API<\/a> can perform actions that are found within the WHM interface. The XML-API was written specifically for remote interactions with cPanel & WHM. That means that a developer must make an HTTP query to invoke the desired function. While the XML-API covers a lot of functionality, the breadth of utility does not cover as much ground as API1 and API2. so the function sets aren’t compartmentalized into modules. However, in our documentation<\/a>, you will find those functions within logical groupings, like “Account functions” and “SSL functions.”<\/p>\n The XML-API, like the name suggests, will return XML formatted results. We also offer a JSON version. The interface (aka, HTTP request format) is the same, it’s just a different path in the URL. Unconventionally, it is completely commonplace to see both the XML and the JSON response\/query types referred to as XML-API, despite the obvious discrepancy in the API’s name.<\/p>\n As it was mentioned earlier, the XML-API can source and manipulate data similar to actions found in the WHM interface. Informally, we call these XML-API functions “native” since they are built right into the XML-API query parser. These native functions are performed as the authenticated, privileged WHM user, namely “root” or a reseller account. This is an important distinction since the XML-API can also perform cPanel actions as a privileged user or end-user! The XML-API can be used as a proxy for API1 and API2 functions. This proxy style query parser is available to all users. If a privileged user makes an API1 or API2 call via the XML-API on either the WHM or cPanel ports, the action will be performed as the user they specify, provided they clear any relevant ACL checks. If a cPanel end-user makes an API1 or API2 call, authenticated as themselves, via the XML-API on a cPanel port, it will perform the action as if from a cPanel page. Details about invoking the XML-API are here<\/a>. Specific information about calling API1 and API2 functions via the XML-API can be found here<\/a>.<\/p>\n There is one other API currently available to developers that should be mentioned. The Manage2 API provides the utility for managing cPanel licenses. The Manage2 API is primarily for those interested in creating a custom interface for viewing and updating their cPanel licenses. Being an HTTP query, these functions are queried in a similar fashion to the XML-API. The response can be formatted in XML, JSON, or YAML. The Manage2 API is documented here<\/a>.<\/p>\n In case you missed Matt Dees’ post<\/a> from earlier this month, he announced the official release of cPanel::PublicAPI. It’s available for download on CPAN<\/a> and our Github repository<\/a>. This is an excellent package for querying these APIs (and some other stuff too) in Perl. For PHP folk, we have the XML-API PHP client class, available on our Github repository<\/a>.<\/p>\n