What Are The Available API Libraries?
Here is a list of all the currently available API libraries that you might find in a normal cPanel environment along with a short description that explains what they are used for:
Reference Libraries:
• UAPI — Access and modify cPanel account data and settings.
• cPanel API 2 — Use UAPI when available, but still pretty good:
• WHM API 1 — Perform server administration tasks.
• Manage2 API — Automate cPanel license management.
Deprecated Libraries:
• cPanel API 1 — Use UAPI instead.
• WHM API 0 — Use WHM API 1 instead.
So basically there are only three API libraries that you might use from the command line, WHM API 1, UAPI, and Manage2 API. However since Manage2 API does not have a readily available command-line interface to use, it will not be discussed here. For more information on Manage2 API you can refer to this link from our official documentation:
https://documentation.cpanel.net/display/DD/Guide+to+the+Manage2+API
Note: Although it is still technically possible to make calls to the Manage2 API right from the command line using tools like curl, since this library is mainly used in relation to license management tasks, we will not intend to discuss it any further in this article.
Where Can I Find The Binaries Associated With These API Libraries From The Command-Line?
These API libraries are available in the form of normal executable utilities that can be accessed right from the command-line by the simple directive invocation of their name. It is usually the case that you can simply call the API name, but in certain cases, you might need to use the absolute path to the location of the executable utility to be able to use the API library. Here are the locations of all the available API executables:
/usr/local/cpanel/bin/cpapi1
/usr/local/cpanel/bin/cpapi2
/usr/local/cpanel/bin/cpapi3 (The same as whmapi1)
/usr/local/cpanel/bin/uapi
/usr/local/cpanel/bin/whmapi0
/usr/local/cpanel/bin/whmapi1
Every binary above is also a symbolic link to this utility:
/usr/local/cpanel/bin/apitool
So conveniently you can always use this utility as an alternative to calling each of the above libraries separately.
How To Find A Particular API Call/Function?
The best way to determine if an API call exists is to search through all the APIs at once. There are at least three different ways to do this:
1- Using The apitool Binary:
The apitool binary is a very handy tool that you can use to list all the available API calls at any time, so naturally, it is very useful if you are looking for a specific API function. All you need to do is to execute the binary and then pipe the output through a grep and search for a specific string that you suspect could appear in the function's name: (You need to replace the $STRING with the search term for which you wish to find relevant API calls)
/usr/local/cpanel/bin/apitool | egrep -i $STRING
Here is an example search where we are looking for API call with the string "dest" in them: (These API calls are related to the remote backup and also email forwarding functionalities in cPanel)
/usr/local/cpanel/bin/apitool | egrep -i dest
backup_destination_add
backup_destination_delete
backup_destination_get
backup_destination_list
backup_destination_set
backup_destination_validate
get_user_email_forward_destination
set_user_email_forward_destination
2- Using A Normal Shell Command:
There are many ways to achieve this with your shell of choice (bash) and here we are using process substitution since the resulting command comes up clean and it's also very customizable in case you wish to tweak the result. And this is the command that you can use to search through all the important and non-deprecated APIs at once: (You need to replace the $STRING with the search term for which you wish find API calls)
grep -Ei "()" <(whmapi1) <(uapi) <(cpapi2) <(/usr/local/cpanel/bin/apitool) | awk -F" " '{ print $2 }'
Again, for the sake of consistency, we search for API calls which contain the string "dest":
egrep -i "(dest)" <(whmapi1) <(uapi) <(cpapi2) | awk -F" " '{ print $2 }'
backup_destination_add
backup_destination_delete
backup_destination_get
backup_destination_list
backup_destination_set
backup_destination_validate
get_user_email_forward_destination
set_user_email_forward_destination
3- Using The API Modules Themselves:
Another way to find a list of expected API Calls would be to parse them directly from the API Modules themselves, by using Perl. This should be able to be done as below: (You need to replace the $STRING with the search term for which you wish find API calls)
/usr/local/cpanel/3rdparty/bin/perl -MCpanel::Template::Plugin::API_Shell -e 'our @apis = (\&Cpanel::Template::Plugin::API_Shell::api2_functions, \&Cpanel::Template::Plugin::API_Shell::whm1_functions, \&Cpanel::Template::Plugin::API_Shell::uapi_functions); my @elemV = (0,1,2) ; foreach (@elemV) { apiC($_) ;} sub apiC { foreach ( @apis[@_]->() ) { my $snipString = "@$_"; $snipString =~ (s/ /\n/g); print "\n$snipString\n"; } } ' | egrep -i "$STRING"
Here is an example search where we are again looking for API calls with the string "dest" in them:
/usr/local/cpanel/3rdparty/bin/perl -MCpanel::Template::Plugin::API_Shell -e 'our @apis = (\&Cpanel::Template::Plugin::API_Shell::api2_functions, \&Cpanel::Template::Plugin::API_Shell::whm1_functions, \&Cpanel::Template::Plugin::API_Shell::uapi_functions); my @elemV = (0,1,2) ; foreach (@elemV) { apiC($_) ;} sub apiC { foreach ( @apis[@_]->() ) { my $snipString = "@$_"; $snipString =~ (s/ /\n/g); print "\n$snipString\n"; } } ' | egrep -i "dest"
backup_destination_add
backup_destination_delete
backup_destination_get
backup_destination_list
backup_destination_set
backup_destination_validate
get_user_email_forward_destination
set_user_email_forward_destination
How To Execute A cPanel's API Call From The Command-Line?
As mentioned above here we are only interested in two API libraries, namely WHM API 1 (executable name = whmapi1) and UAPI (executable name = uapi), so we will discuss how to execute functions only from these two API libraries.
A Rule Of Thumb:
When you search for a specific call/function using any of the methods above, there is a very simple rule of thumb that you can use to determine to which API library a particular call/function belongs, so that you can invoke the appropriate executable name.
Here is the rule of thumb:
" If you see capital letters and/or double colons (::) in the function's name, then that function belongs to the UAPI library, otherwise it belongs to the WHM API 1 library."
Let's test this rule by searching for all the functions related to the cPanel's greylisting functionality:
egrep -i "(grey|gray)" <(whmapi1) <(uapi) <(cpapi2) | awk -F" " '{ print $2 }'
- - - - - - - - - - - - - - - - - - - - - - - - - -
WHM API 1 calls:
cpgreylist_is_server_netblock_trusted
cpgreylist_list_entries_for_common_mail_provider
cpgreylist_load_common_mail_providers_config
cpgreylist_save_common_mail_providers_config
cpgreylist_status
cpgreylist_trust_entries_for_common_mail_provider
cpgreylist_untrust_entries_for_common_mail_provider
create_cpgreylist_trusted_host
delete_cpgreylist_trusted_host
disable_cpgreylist
enable_cpgreylist
load_cpgreylist_config
read_cpgreylist_deferred_entries
read_cpgreylist_trusted_hosts
save_cpgreylist_config
- - - - - - - - - - - - - - - - - - - - - - - - - -
UAPI calls: (Notice the capital letters and also the double colons (::))
cPGreyList::disable_all_domains
cPGreyList::disable_domains
cPGreyList::enable_all_domains
cPGreyList::enable_domains
cPGreyList::has_greylisting_enabled
cPGreyList::list_domains
As you can see all the calls that have a capital letter and/or double colon in their name belong to the UAPI and all the other functions belong to the WHM API 1.
WHM API1 (AKA whmapi1):
The general syntax for executing a particular WHM API 1 function is this:
whmapi1 [options] [function] [uri-key=uri-value] [uri-key=uri-value] ....
As an example, we might see how we can get the hostname of the server using an API call. First, quite expectedly, we must look for all the API calls with the string "hostname" in their name:
egrep -i "(hostname)" <(whmapi1) <(uapi) <(cpapi2) | awk -F" " '{ print $2 }'
gethostname
sethostname
The first option seems to be what we are looking for, so now all we have to do is to invoke that function using the general syntax mentioned above:
whmapi1 gethostname
---
data:
hostname: server.test-001.net
metadata:
command: gethostname
reason: OK
result: 1
version: 1
However, not all the functions are as simple as this one. Some are more involved and require more parameters. You can always refer to our official developer documentation to see what parameters and options are available and also how to interpret the output of an API call:
https://documentation.cpanel.net/display/DD/Developer+Documentation+Home
UAPI (AKA uapi):
Similarly, the general syntax for executing a particular UAPI function is this: (Here a module refers to what comes before the double colon (::))
uapi [options] [module] [uri-key=uri-value] [uri-key=uri-value] ....
As an example, we might be interested to know if one of our users/accounts has access to a feature that allows them to create subdomains. Again first, we must look for all the API calls with the string "feature" in their name, but this time we are looking for UAPI calls because this is only user-level information and from the short description given at the beginning of the article we know that user-level informant is usually available through UAPI calls.
egrep -i "(feature)" <(whmapi1) <(uapi) <(cpapi2) | awk -F" " '{ print $2 }' | egrep -i "::"
Features::get_feature_metadata
Features::has_feature
Features::list_features
The second option seems to be what we are looking for, so now all we have to do is to invoke that function using the general syntax mentioned above plus the information available in the developer documentation about this function (here): (The username is "cptest" and the feature name is "subdomain")
uapi --user=cptest Features has_feature name=subdomain
---
apiversion: 3
func: has_feature
module: Features
result:
data: ~
errors: ~
messages: ~
metadata: {}
status: 1
warnings: ~
To summarize the output above, this means that the feature to create a subdomain exists for the user "cptest" on the system and it is also currently enabled.
Please bear in mind that the ultimate source of information on how to use cPanel's APIs is always our official developer documentation which can be found here:
https://documentation.cpanel.net/display/DD/Developer+Documentation+Home