The Community Forums

Interact with an entire community of cPanel & WHM users!
  1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

asking about using xml api for WHM

Discussion in 'cPanel Developers' started by a-khamis, Jul 5, 2012.

  1. a-khamis

    a-khamis Registered

    Joined:
    Jul 5, 2012
    Messages:
    3
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    Reseller Owner
    hello ,

    i would like to ask about the correct steps to using xml api , and i want some informations about :

    i will make a hosting script with asp.net hosted in another remote server , i want this script reach to my whm . so

    please can any one answer me for the following :

    how to install and setup the authentication in the xml api ?

    # i downloaded the xml api from cpanel.net is it enough ?

    thanks

    best regards
     
    #1 a-khamis, Jul 5, 2012
    Last edited: Jul 5, 2012
  2. Infopro

    Infopro cPanel Sr. Product Evangelist
    Staff Member

    Joined:
    May 20, 2003
    Messages:
    14,456
    Likes Received:
    195
    Trophy Points:
    63
    Location:
    Pennsylvania
    cPanel Access Level:
    Root Administrator
    Twitter:
  3. a-khamis

    a-khamis Registered

    Joined:
    Jul 5, 2012
    Messages:
    3
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    Reseller Owner
    thank you for your reply but i have a simple question how can i install the xml api . or what i need to integrate my script with my WHM and i want to know what is xml-api directory and what is it contain and where i put it ?
     
    #3 a-khamis, Jul 5, 2012
    Last edited: Jul 5, 2012
  4. sw_sp

    sw_sp Registered

    Joined:
    Jul 5, 2012
    Messages:
    1
    Likes Received:
    0
    Trophy Points:
    1
    cPanel Access Level:
    Reseller Owner
    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
     
  5. cPanelDavidG

    cPanelDavidG Technical Product Specialist

    Joined:
    Nov 29, 2006
    Messages:
    11,279
    Likes Received:
    8
    Trophy Points:
    38
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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.
     
  6. cPanelDavidN

    cPanelDavidN Integration Developer
    Staff Member

    Joined:
    Dec 17, 2009
    Messages:
    571
    Likes Received:
    1
    Trophy Points:
    18
    Location:
    Houston, TX
    cPanel Access Level:
    Root Administrator
    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
     
    #6 cPanelDavidN, Jul 6, 2012
    Last edited: Jul 7, 2012
Loading...

Share This Page