Development Guides Home >> Quickstart Development Guide

Tutorial - Replace a cPanel API 1 Function With a UAPI Function

Introduction

This tutorial shows how to replace a deprecated cPanel API 1 function with a UAPI function in a cPanel integration or plugin. As 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 in LiveAPI Perl

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.

The example below uses 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

This example directs 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.
An error message if the system encounters an error when it calls the function.
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';
}

Replace a cPanel API 1 function in LiveAPI PHP

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.

The example below uses 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

The following example directs 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.
An error message if the system encounters an error when it calls the function.
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 examples:

LiveAPI Perl

#!/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();

LiveAPI PHP

<?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';
}

?>