NAME

cPanel::APIClient - cPanel APIs, à la TIMTOWTDI!

SYNOPSIS

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();

DESCRIPTION

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.

FEATURES

• 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.

CHARACTER ENCODING

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!

FUNCTIONS

$client = cPanel::APIClient->create( %OPTS )

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:

  • cpanel - Function will return a cPanel::APIClient::Service::cpanel
    instance.
  • whm - Function will return a cPanel::APIClient::Service::whm
    instance.

• 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.

  Currently supported mechanisms are:

  • cPanel::APIClient::Transport::HTTPSync (HTTPSync) -
    Synchronous HTTP requests.
  • cPanel::APIClient::Transport::CLISync (CLISync) -
    Synchronous local requests via cPanel & WHM’s command-line API tools.
  • 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.
  • cPanel::APIClient::Transport::MojoUserAgent (MojoUserAgent) -
    Asynchronous HTTP requests via Mojo::UserAgent (pure Perl).

  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:

  • username & api_token - Authenticate with an API token
  • username & password - Authenticate with a password
  • username, password, & tfa_token - Authenticate with a
    password and two-factor authentication (2FA) 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.

LICENSE

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.