Matthew Dees > cPanel-PublicAPI > cPanel::PublicAPI

Download:
cPanel-PublicAPI-1.002.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  0
View/Report Bugs
Module Version: 1.002   Source  

NAME ^

cPanel::PublicAPI - A perl interface for interacting with cPanel

SYNOPSIS ^

  use cPanel::PublicAPI;
  
  # Auto detect authentication information
  my $cp = cPanel::PublicAPI->new();
  # or specify a user/password
  my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'pass' => 'somepass' );
  # or specify an accesshash
  my $cp = cPanel::PublicAPI->new('user' => 'someuser', 'accesshash' => $accesshash );
  
  # Perform an xml-api query
  $cp->whm_api('listaccts');
  # Pass parameters to the xml-api
  $cp->whm_api('createacct', {'username' => 'someuser', 'password' => 's0m3P4$$w()Rd' } );
  # Return JSON from xml-api (rather than a hash reference)
  $cp->whm_api('version', undef, 'json');
  
  # Perform an API2 query
  $cp->cpanel_api2_request('whostmgr',
    {
      'module' => 'Email',
      'func' => 'listpopswithdisk',
      'user' => 'someuser',
    }
  );
  # Perform an API2 query when authenticated as a user
  $cp->cpanel_api2_request('cpanel',
    {
      'module' => Email,
      'func' => 'listpopswithdisk',
    }
  );
  # Pass parameters to an API2 call
  $cp->cpanel_api2_request('cpanel'
    { 
        'module' => 'Email',
        'func' => 'addpop',
    },
    {
        'domain' => 'domain.com',
        'email' => 'username',
        'password' => 'SojmASDM(#(Jinasifodanosd',
        'quota' => 200
    },
  );
  
  # Perform an API1 query
  $cp->cpanel_api1_request('whostmgr',
    {
        'module' => 'LastLogin',
        'func' => 'lastlogin',
        'user' => 'someuser'
    }
  )
  # Pass parameters to an API1 query
  $cp->cpanel_api1_request('cpanel',
    {
        'module' => 'Mysql',
        'func' => 'adduserdb',
    },
    [ 'somedb', 'somedbuser', 'ALL' ]
  );
  
  # perform an HTTP GET request against a URL
  $cp->api_request('whostmgr', '/xml-api/laodavg', 'GET');
  
  # perform an HTTP GET request with parameters
  $cp->api_request('whostmgr', '/xml-api/createacct', 'GET', {'username' => 'someuser', domain => 'domain.com'} );
  
  # perform an HTTP POST request (with parameters)
  $cp->api_request('whostmgr', '/xml-api/createacct', 'POST', {'username' => 'someuser', domain => 'domain.com'} );

DESCRIPTION ^

cPanel::PublicAPI is a supported interface for interacting with cPanel's APIs over HTTP. This allows you to query either WHM or cPanel accounts from a perl interface. The purpose of this module is to provide an easy-to-use interface into cPanel's various APIs without requiring much knowledge of how they work.

Object Construction

A cPanel::PublicAPI object is constructed with the new() method.

  my $publicapi = cPanel::PublicAPI->new();

When passed no parameters this create the object using the accesshash in ~/.accesshash. If no .accesshash file exists, it will attempt to use the REMOTE_PASS environment variable, if that is not defined, object creation will error out.

new() parameters

options for new() are specified as a hash reference, the following parameters are supported:

Notes about authentication

There are two sets of credentials that can be used to authenticate to WHM.

First we have the basic user/password combinations:

  use Cpanel::PublicAPI;
  my $pubapi = Cpanel::PublicAPI->new( 'user' => 'foo', 'password' => 'bar' );

The other type of authentication is accesshash authentication. To configure accesshashes visit “Setup remote access key” in WHM which will generate an accesshash for your server if one does not already exist. It will store the generated accesshash in /root/.accesshash. To use an accesshash with this module you can do something like the following:

  use Cpanel::PublicAPI;
  my $pubapi = Cpanel::PublicAPI->new( 'user' => 'foo', 'accesshash' => $string_containing_access_hash );

It should be noted that the access hash can contain newlines in it, Newlines will be stripped by the object when it attempts to perform a query.

Dependencies

This module will fall back on different modules if one fails to load. This allows for compatibility with cPanel & WHM's internal perl parser and maintain compatibility with a standard perl implementation. The order that it will fall back on serialization modules is:

If you installed this module via CPAN, this should never be an issue. If you are wishing to use this module on a system where you do not have access to compiled modules, JSON::PP is the recommended serializer.

Important Methods ^

Querying the xml-api - whm_api()

The XML-API is WHM's API used for administrative functions is handled via the whm_api() method.

The syntax for whmapi is:

  $cp->whm_api($call [, \%formdata, $format ] );

The meaning of these parameters is:

For more information on what calls are available and how they can be referenced, please see the xml-api documentation at http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/XmlApi.

Querying cPanel's APIs

cPanel supports two APIs, designated "API1" and "API2".

cPanel API calls are seperate into Modules, these module names relate to modules within the Cpanel namespace on a cPanel server. Each module defines a set of functions that are from either API1 or API2 (or both).

There are two distinct differences between API1 and API2:

Within the context of the public api, calling a function from API1 or API2 will always return a hash, but the specific data returned from the API call will be contained within the 'data' key of the response.

For more information on the differences between API1 and API2 please see the documentation: http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/ApiIntroduction

For information on calling API1 and API2 direct via HTTP, please see: http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/CallingAPIFunctions

cpanel_api1_request()

cpanel_api1_request() is used to query cPanel's API1, the function used for querying API1 has the following syntax:

  $cp->cpanel_api1_request($service, \%cfg [, \@params, $format ] );

To see what modules and functions are available for making API1 calls, please see: http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api1/WebHome

cpanel_api2_request()

cpanel_api2_request() is used to query cPanel's API2, the function use for querying API2 has the following syntax:

  $cp->cpanel_api2_request( $service, \%cfg [, \%params, $format ] );

To see what modules and functions are available for making API2 calls, please see: http://docs.cpanel.net/twiki/bin/view/ApiDocs/Api2/WebHome

api_request() - Making direct URL requests to cPanel & WHM.

There are some situations where you will need to query cPanel and WHM URLs directly. This should ONLY be done when there is not an API call available for the function you wish to query.

The function used for querying URLs directly is api_request(). It will always return a string rather than converting the response into a hash reference. It uses the following syntax:

  $cp->api_request( $service, $uri, $method, \%formdata, $headers)

Other Features ^

set_debug()

This function allows you to enable/disable debug mode by passing a value that evaluates to 'true' or 'false'.

user()

Allows you to change the user that your PublicAPI object is authenticating with.

pass()

Allows you to change the password that your PublicAPI object is authenticating with, this will remove the stored accesshash from the object.

accesshash()

Allows you to change the accesshash that your PublicAPI object is authenticating with, this will remove the stored password from the object.

format_http_query()

Allows you to construct form data for an http query from a hash. For Example:

  $pubapi->format_http_query( { 'one' => '1', 'two' => 2 } );

would return:

  'one=1&two=2'
format_http_headers()

Allows you to construct headers for an http query from a hash. For example:

  $pubapi->format_http_headers( { 'Authorization' => 'Basic cm9vdDpsMGx1cnNtNHJ0IQ=='} );

would return:

  'Authorization: Basic cm9vdDpsMGx1cnNtNHJ0IQ==\r\n'
$pubapi-\{'error'}>

Errors encountered within the class are stored here before being written out to the error_fh filehandle. This can be used for checking the existance of query errors.

Bugs ^

see http://rt.cpan.org to report and view bugs

License ^

Copyright (c) 2011, cPanel, Inc. All rights reserved. http://cpanel.net

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of cPanel, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

syntax highlighting: