asking about using xml api for WHM

question about /xml-api/ directory

hi ,

i have a reseller account and i want to use xml api to automatically creating accounts . i saw all the documentations for whm sdk and i understand how to call the functions but i don't know what xml-api directory and i didn't saw any thing about installing the xml api .

can any one please explain to me what is this directory and where can i find it or if i should place it where i have to place it and what is it contain ?

is the company (that provide to me the reseller account) responsible to add the the api or i have to do this by my self ?

regards

 

The API itself does not require installation, it's already on every cPanel & WHM system running version 11.0.0 (released about 6 years ago) or later ready for you to use.

If you are accessing cPanel functionality, you would access it via (the address to your cPanel ending in :2083 or :2082)/xml-api (e.g. https://example.com:2083/xml-api). For WHM functionality or if you are logging in using a reseller or root account, switch the cPanel ports with WHM port numbers.

If you are using PHP or Perl, you can find sample code at cPanel & WHM's SDK - if you are using another language (e.g. ASP.NET) then you will need to spend time understanding how the API works, how to interact with it and build your own custom code to interact with the API. If you are familiar with XML RPC-style APIs, then you should find this relatively easy.

 

The Remote API (often referred to as the XML API or JSON API) is a HTTP based server-side interface for performing administrative actions. Programs can make HTTP based requests to a WHM server and receive back either a JSON or XML formatted response. If you wish to make a Remote API request it will need to be in the format specified in the documentation. The following is an example of a HTTP GET URL:

Code:

$protocol://$server_name_or_address:$port/(xml|json)-api/$function_name?$key=$value&$key_2=$value_2

• $protocol will be either http or https. We highly recommend using https
• $server_name_or_address is the fully qualified domain name that WHM resolves on, or you can just use the IP address
• $port will be 2086 for WHM's http port, 2087 for WHM's https. (you can also use port 2082 and 2083 if you're using the Remote API as a proxy to trigger API1 or API2 functions with cPanel user credentials). As with the protocol, we highly recommend using SSL...so, port 2087 is the best
• If you want an XML formatted response, the first segment of the URL following the server : port should be xml-api. If you want a JSON formatted response, use json-api
• $function_name is the administrative function that you which to call, like "createacct" or "addip"
  each administrative function has it's own set of parameters (represented as key and value in the example above); you'll need to reference the documentation for the required parameters.

Your program can make the HTTP request as a GET or POST. Usually, it's preferable to submit it as a POST simply because some calls, like "createacct", have many parameters and it's easy to reach the technical character limit of a GET request.

In order for your request to be accepted by the WHM server, it will need to include authentication credentials. Each request must pass credentials...there is not authentication token exchange. Credentials are passed as part of the header content of the HTTP request. There are two different authentications you can use:

1) Basic administrative user credentials
This is would be either root's username/password or a reseller with proper permissions to complete the requested administrative function
In this case your program needs to add an HTTP header like

Code:

'Authorization: Basic ' . base64_encode( $username . ':' . $password ) . "\r\n"

...the header key is "Authorization" and the value is the word "Basic" followed by a space, followed by the username, a colon, and password, all base64 encoded.

2) Remote access hash
You can generate a remote access hash on the WHM server and use it kind of like an API key. If you have made one it would be like

Code:

'Authorization: WHM ' . $username . ':' . $access_hash . "\r\n"

...the value of "Authorization" is the word "WHM" followed by a space, followed by the username who owns the access hash (likely root), a colon, the access hash.

Most people create a class or set of functions that do all this HTTP request preparation for them. One example of this is the PHP Client Class that we host on our GitHub page. PHP programs can include this class and have easy methods for creating the HTTP request, without having to understand the URL structure or manually construct the HTTP header content; all the heavy lifting is done for them by the methods of that class.

If your program in not written in PHP, that class and the other items available in that download will not be very useful. We do not maintain an ASP.net client class/library. You will have to make your own or find one that someone else has shared (search google or the forums [or google the forums]...iirc, there's a post or two about handling the HTTP headers in ASP).

There is NOTHING you need to do on you WHM server in order to make Remote API requests. It is always available and there is no configuration necessary. Making programmatic calls to WHM is simply a matter of submitting a well-formed HTTP request that contains valid credentials in the header and has the proper URL address and parameters.

You can even manually make Remote API requests, just to get the feel of it. In your browser, log into WHM. Once you login, your browser will keep you authenticated, so you don't need to be concerned with the header information. Now, you can manually put in the Remote API URL and parameters in the browser's address bar. When you hit "enter" or the "go" button, the browser will submit the request via a GET query and the response will be printed as plain text in the browser's window (or may be pretty formatted by the browser, ymmv).

Regards,
-DavidN