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
