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.

API2 Basics?

Discussion in 'cPanel Developers' started by mikelegg, Dec 17, 2008.

  1. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    I've had a little experience coding with the old cPanel Accounting Module in PHP, but I'd like to start using the new API2.

    I've browsed through the docs at http://www.cpanel.net/plugins/api2/index.html

    But I can't find anything that spells out how to actually use the API2 Tags in a real-world situation.

    Can anyone point me in the right direction?
     
  2. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    Looking through the forums it appears that I'm not the first person to ask this question.

    So I'll try to work this out and post my results here for the benefit of everyone who has asked.

    The first things I've noticed are.

    1) Be careful of what you find via Google searches because most of it deals with the old cPanel Accounting module.
    2) The secret to using the cPanel API2 tags in PHP seems to be Curl. I'll try and post some sample code when I work out how to do it.
     
  3. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    I'm getting nowhere fast. I've gathered a few cryptic clues from varous forum posts but I can find no clear explanation of how to implement the API in an actual script.

    I think https://user:pass@server:2086/xml-api/applist should return all available XML API functions from the cPanel server, but it doesn't return anything for me.

    Can anyone give me a couple more clues as to how to do this?
     
  4. 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 XML API (not API2 directly) can be accessed by logging into WHM and then entering specific URLs.

    Try logging into WHM and then going to https://server:2087/xml-api/applist or http://server:2086/xml-api/applist

    Do you see any XML output now?
     
  5. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    Thanks David

    I was trying to run it from another server, not the server itself.

    If I log into WHM and paste the link into the address bar, I can get it to return the app list, but it prompts me to log in again.

    What I really want to do is access the details of remote servers, not the local one- is there a way to do this?
     
    #5 mikelegg, Dec 18, 2008
    Last edited: Dec 18, 2008
  6. 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
    Sure, here's a simplistic PHP script that demonstrates how you can connect to a remote server to execute API calls.

    PHP:
    // VARIABLES:
    //   $hash = your hash (not needed if using password authentication)
    //   $user = username for the reseller accompanying that hash
    //   $pass = password for that reseller (not needed if using hash authentication)
    //   $theServer = your server's hostname or IP

    # What is the path to the API function you wish to use?
    $apiPath '/xml-api/gethostname';

    // NOTE:
    //    THIS CODE WILL ONLY WORK IF YOU HAVE ENABLED
    //    OPENSSL IN PHP.  YOU CAN DO THIS BY GOING TO WHM
    //    AND IN THE SOFTWARE SECTION, CLICK ON APACHE UPDATE
    //    THEN LOAD PREVIOUS CONFIG AND THEN CHECK THE BOX
    //    NEXT TO OPENSSL TO ENABLE SSL SUPPORT
    //
    // Of course, you could always go with http:// and 2086, but why?

    # Make hash into one long string, in case it isn't already
    $hash str_replace("\n",'',$hash); // Note \r is not part of the newline indicator on *nix systems.

    # Open a socket for HTTPS
    $fp fsockopen('ssl://' $theServer2087$errno$errstr30);

    # Uncomment to use unsecure HTTP instead
    //$fp = fsockopen($theServer, 2086, $errno, $errstr, 30);

    # Die on error initializing socket
    if ($errno == && $fp == FALSE) {
     die(
    'Socket Error: Could not initialize socket.');
    } elseif (
    $fp == FALSE) {
     die(
    'Socket Error #' $errno ': ' $errstr);
    }

    # Assemble the header to send
    $header '';
    $header .= 'GET ' $apiPath " HTTP/1.0\r\n";
    $header .= 'Host: ' $theServer "\r\n";
    $header .= "Connection: Close\r\n";
    $header .= 'Authorization: WHM ' $user ':' $hash "\r\n";
    # Comment above line and uncomment below line to use password authentication in place of hash authentication
    //$header .= 'Authorization: Basic ' . base64_encode($user . ':' . $pass) . "\r\n";
    $header .= "\r\n";

    # Send the Header
    fputs($fp$header);

    # Get the raw output from the server
    $rawResult '';
    while (!
    feof($fp)) {
     
    $rawResult .= @fgets($fp128); // Suppress errors with @
    }

    # Close the socket
    fclose($fp);

    # Ignore headers
    $rawResultParts explode("\r\n\r\n",$rawResult);
    $result $rawResultParts[1];

    # Output XML
    echo $result;
    With minimal knowledge of PHP, you can customize this code to make API calls to multiple servers. Just remember that access hashes are typically unique to each account on each server.

    You will need reseller access or better on those remote servers to be able to use the APIs on those servers. Also note, you can't do anything via the API that you wouldn't be able to do via the WHM interface with the same credentials.
     
  7. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    Thanks David

    Now I've got some idea of how it all works - it's not unlike using the old cPanel Accounting functions.

    I'll generally be logging in as root so I should be able to access all domains on the servers.
     
  8. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    One more question ... what syntax is used to specify an API2 path?

    I've used /xml-api/listaccts to build an array of domains, now I'd like to use
    Email::listmaildomains to get all parked and addon domains that have mail addresses on the account.

    The sample code in the documentation is ...

    <?cp Email::listmaildomains( %, domain) skipmain=1 ?>

    But obviously that syntax won't work in PHP.

    I think it's something like'/xml-api/cpanel?listmaildomains&domain='. $domain .'&skipmain=1', but that's not working for me at present.

    I've also tried '/xml-api/cpanel?user=root&xmlin=<cpanelaction><module>Email</module><apiversion>2</apiversion><func>listmaildomains</func><args><domain>'. $domain .'</domain></args></cpanelaction>'
    But it doesn't return anything.
     
    #8 mikelegg, Dec 18, 2008
    Last edited: Dec 18, 2008
  9. 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 space after Email in:

    Code:
    ...<cpanelaction><module>Email </module>...
    is a likely cause of no data being returned.
     
  10. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    The space isn't in my code, it just appears in the post after I save it.

    If I edit the post it doesn't appear, so I can't remove it.
     
  11. 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
    What's your full cPanel/WHM version information?
     
  12. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    cPanel 11.24.2-C32034 - WHM 11.24.2 - X 3.9
     
  13. 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
    Okay.

    You mention that nothing is being returned. So if not even an error message is being returned, are you sure the connection to the server is properly established?
     
  14. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    The connection is working because what I'm doing is creating an array of domains using /xml-api/listaccts (which is working fine).

    Then I'm looping through the array of domains and executing /xml-api/cpanel?user=titan&xmlin=<cpanelaction><module>Email</module><apiversion>2</apiversion><func>listmaildomains</func><args><domain>'. $domain .'</domain></args></cpanelaction> for each domain in the array.

    It's only this second call that's not returning anything.

    I've assumed there are accounts on the server that have email addresses on secondary domains - but maybe I've assumed wrong?
     
  15. 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
    Are you also changing the username for user= to reflect the cPanel user for that domain as well in your loop?
     
  16. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    No, when I tried that it returned some HTML which looked like a login page. So I changed to using the reseller username.

    I'll try it again and see what happens.
     
  17. mikelegg

    mikelegg Well-Known Member

    Joined:
    Mar 29, 2005
    Messages:
    330
    Likes Received:
    0
    Trophy Points:
    16
    That's got it.

    Thanks for your help David.
     
Loading...

Share This Page