cPanel::APIClient - cPanel APIs, à la TIMTOWTDI!
Create a cPanel::APIClient::Service::cpanel object to call cPanel APIs:
my $cpanel = cPanel::APIClient->create( service => 'cpanel', transport => [ 'CLISync' ], ); my $resp = $cpanel->call_uapi( 'Email', 'list_pops' ); my $pops_ar = $resp->get_data();
Create a cPanel::APIClient::Service::whm object to call WHM APIs:
my $whm = cPanel::APIClient->create( service => 'whm', transport => [ 'CLISync' ], ); my $resp = $whm->call_api1( 'listaccts' ); my $accts_ar = $resp->get_data();
cPanel & WHM exposes a number of ways to access its APIs: different transport mechanisms, different authentication schemes, etc. This library provides client logic with sufficient abstractions to accommodate most supported access mechanisms via a unified interface.
This library intends to supersede cPanel::PublicAPI as the preferred way to access cPanel & WHM’s APIs from Perl. It can also serve as a model for similar client libraries in other languages.
Fully object-oriented.
Can use blocking or non-blocking I/O. Non-blocking I/O implementation works with almost any modern Perl event loop interface.
Uses minimal dependencies: no Moose &c.
Extensively tested.
Can run in pure Perl.
cPanel & WHM’s API is character-set-agnostic. All text that you give to this library should thus be encoded to binary, and all strings that you’ll receive back will be binary.
This means that if you character-decode your inputs—as perlunitut recommends—then you’ll need to encode your strings back to bytes before giving them to this module.
Use of UTF-8 encoding is strongly recommended!
A factory function that creates a “client” object that your code can use to call the APIs.
%OPTS are:
service - Required. The service that exposes the API(s) to call. This controls the class of the returned object. Recognized values are:
service
cpanel - Function will return a cPanel::APIClient::Service::cpanel instance.
cpanel
whm - Function will return a cPanel::APIClient::Service::whm instance.
whm
transport - Required. An array reference that describes the transport mechanism to use. The first member of this array names the mechanism; remaining arguments are key-value pairs of attributes to give to the mechanism class’s constructor.
transport
Currently supported mechanisms are:
cPanel::APIClient::Transport::HTTPSync (HTTPSync) - Synchronous HTTP requests.
HTTPSync
cPanel::APIClient::Transport::CLISync (CLISync) - Synchronous local requests via cPanel & WHM’s command-line API tools.
CLISync
cPanel::APIClient::Transport::NetCurlPromiser (NetCurlPromiser) - Asynchronous HTTP requests via Net::Curl::Promiser, which can use any event loop interface. As of this writing it supports IO::Async, AnyEvent, and Mojolicious out-of-the-box.
NetCurlPromiser
cPanel::APIClient::Transport::MojoUserAgent (MojoUserAgent) - Asynchronous HTTP requests via Mojo::UserAgent (pure Perl).
MojoUserAgent
Which of the above to use will depend on your needs. If your application is local to the cPanel & WHM server you might find it easiest to use CLISync. For HTTP NetCurlPromiser offers the best flexibility and (probably) speed, whereas MojoUserAgent and HTTPSync can run in pure Perl (assuming you have Net::SSLeay).
There currently is no documentation for how to create a 3rd-party transport mechanism (e.g., if you want to use a different HTTP library). Submissions via pull request will be evaluated on a case-by-case basis.
credentials - Some transports require this; others don’t. The recognized schemes are:
credentials
username & api_token - Authenticate with an API token
username
api_token
username & password - Authenticate with a password
password
username, password, & tfa_token - Authenticate with a password and two-factor authentication (2FA) token.
tfa_token
username only - Implicit authentication, only usable for local transports.
Depending on the service given, this function returns an instance of either cPanel::APIClient::Service::cpanel or cPanel::APIClient::Service::whm.
Copyright 2020 cPanel, L. L. C. All rights reserved. http://cpanel.net
This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install cPanel::APIClient, copy and paste the appropriate command in to your terminal.
cpanm
cpanm cPanel::APIClient
CPAN shell
perl -MCPAN -e shell install cPanel::APIClient
For more information on module installation, please visit the detailed CPAN module installation guide.