We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Child pages
  • Tutorial - Replace a cPanel API 1 Function With a UAPI Function
Skip to end of metadata
Go to start of metadata

Introduction

This tutorial shows how to replace a deprecated cPanel API 1 function with a UAPI function in a cPanel integration or pluginAs of cPanel & WHM version 86, the system sends you a notification if any of your cPanel plugins or custom cPanel integrations use cPanel API 1 functions. We plan to remove the cPanel API 1 framework in cPanel & WHM version 88. You must replace any cPanel API 1 function in your code with a UAPI or cPanel API 2 function before you upgrade to cPanel & WHM version 88. 

To retrieve a list of cPanel API 1 functions that run on your system, call the following WHM API 1  functions.

For more information, read our Guide to Replacing cPanel API 1 Functions with UAPI Equivalents documentation.

Replace a cPanel API 1 function

Note:

The following examples replace the cPanel API 1 SetLang::setlang function with the UAPI Locale::set_locale function.



Open the file.

Open the .live.pl file that contains the cPanel API 1 function. The code will resemble the following example:  

#!/usr/bin/perl 
  
# Instantiate the Cpanel::LiveAPI object.
use Cpanel::LiveAPI ();

print "Content-type: text/html\r\n\r\n";
  
# Connect to cPanel - only do this once.
my $cpliveapi = Cpanel::LiveAPI->new();

print $cpliveapi->header("Set the server's locale to English.");

# Call the function
my $response = $cpliveapi->api1('SetLang', 'setlang', ['en'] ); 

print $cpliveapi->footer();

$cpliveapi->end();




Replace the cPanel API 1 function with its UAPI function equivalent.

Locate the line that contains the cPanel API 1 function. This will resemble the following example:

# Call the function
my $response = $cpliveapi->api1('SetLang', 'setlang', ['en'] );

Replace that line with the appropriate UAPI function. 

In the example below, lines 14-19 use LiveAPI's uapi() method to call UAPI's Locale::set_locale function. 

# Call the function
my $response = $cpliveapi->uapi(
    'Locale', 'set_locale',
    {
        'locale' => 'en',
    }
);

Set the function's return.

Lines 21 through 30 direct the system to return the following: 

  • The {'cpanelresult'}{'result'} node of the last response that the system returned. The format of this data varies based on the last call that the system performed. 
  • Line 25 returns an error message if the system encounters an error when it calls the function. 
  • Line 29 returns a success message if the function succeeds.
my $result = $response->{'cpanelresult'}{'result'};

if (!$result->{status}) {
	# There is an error
	print "The API request failed due to the following error(s):<br>\n";
	print join("<br>\n", $result->{'errors'});
}
else {
	print 'Success';
}

Open the file.

Open the .live.php file that contains the cPanel API 1 function. The code will resemble the following example:  

<?php

require_once "/usr/local/cpanel/php/cpanel.php";

// Connect to cPanel - only do this once.
$cpanel = new CPANEL();
echo $cpanel->header("Set the server's locale to English.");

//Call the function.
$result = $cpanel->api1('SetLang', 'setlang', ['en'] );

echo $cpanel->footer();

?>


Replace the cPanel API 1 function with its UAPI function equivalent.

Locate the line that contains the cPanel API 1 function. This will resemble the following example:

//Call the function.
$result = $cpanel->api1('SetLang', 'setlang', ['en'] );

Replace that line with the appropriate UAPI function. 

In the example below, lines 10-15 use LiveAPI's uapi() method to call UAPI's Locale::set_locale function.

//Call the function.
$response = $cpanel->uapi(
    'Locale', 'set_locale', 
    array(
        'locale' => 'en',
    ) 
);




Set the function's return.

Lines 17 through 25 direct the system to return of the following: 

  • The ['cpanelresult']['result'] node of the last response that the system returned. The format of this data varies based on the last call that the system performed. 
  • Line 20 returns an error message if the system encounters an error when it calls the function. 
  • Line 24 returns a success message if the function succeeds.
$result = $response['cpanelresult']['result'];
if ( !$result['status'] ) {
	// There is an error.
	echo "The API request failed due to the following error(s):,br>\n";
	echo join("<br>\n", $result['errors']);
}
else {
	echo 'Success';
}

Completed code

When you finish this tutorial, your code will resemble the following example:

#!/usr/bin/perl 
  
# Instantiate the Cpanel::LiveAPI object.
use Cpanel::LiveAPI ();

print "Content-type: text/html\r\n\r\n";
  
# Connect to cPanel - only do this once.
my $cpliveapi = Cpanel::LiveAPI->new();

print $cpliveapi->header("Set the server's locale to English.");

#Call the function
my $response = $cpliveapi->uapi(
    'Locale', 'set_locale',
    {
        'locale' => 'en',
    }
);

my $result = $response->{'cpanelresult'}{'result'};

if (!$result->{status}) {
	# There is an error
	print "The API request failed due to the following error(s):<br>\n";
	print join("<br>\n", $result->{'errors'});
}
else {
	print 'Success';
}

print $cpliveapi->footer();

$cpliveapi->end();
<?php

require_once "/usr/local/cpanel/php/cpanel.php";

//Connect to cPanel - only do this once
$cpanel = new CPANEL();
echo $cpanel->header("Set the server locale to English.");

//Call the function
$response = $cpanel->uapi(
    'Locale', 'set_locale', 
    array(
        'locale' => 'en',
    ) 
);

$result = $response['cpanelresult']['result'];
if ( !$result['status'] ) {
	// There is an error
	echo "The API request failed due to the following error(s):<br>\n";
	echo join("<br>\n", $result['errors']);
}
else {
	echo 'Success';
}

?>