Using the API in a Browser and Constructing the API URL<\/span><\/b><\/p>\n The easiest way to get familiar with the cPanel API is to call a function using your browser. Just like visiting a website by entering a URL, you can enter a URL that will perform API calls. During your use of the WHM interface you’ve likely noticed additional data after the typical URL of https:\/\/x.x.x.x:2087<\/a> and we can manipulate that data to perform administrative functions on the server. Although calling functions using the API may seem redundant since you’re already logged into WHM, and thus have full access to the interface and available GUI tools, it will let you see if your API call works as you expect and gives you some helpful output (in either JSON or XML format, whichever you prefer) if you do run into problems.<\/p>\n Here’s an image that shows the basic formatting of an API call – this looks a lot like the familiar WHM login of https:\/\/x.x.x.x:2087<\/a> but just includes extra data after the session ID.<\/p>\n ***NOTE*** Using the URL<\/span><\/b><\/p>\n Now that we have a basic idea of what the URL should look like, let’s perform a basic task with the API – creating a DNS zone. According to the functions page listed earlier in this guide we’ll want to use the “adddns” function. If we follow the URL formatting guide above and the layout details from the function guide at http:\/\/documentation.cpanel.net\/disp…API+1+-+adddns<\/a> we can construct our URL to look like this:<\/p>\n If we analyze this command using the above URL breakout image we have the following areas::<\/p>\n -The “output format” is JSON<\/p>\n -we’re using the “adddns” function<\/p>\n -The API version we’re using is version 1<\/p>\n The rest of the command is the variables that the function requires to operate. I’ve just used “example.com” for the domain to create and I’m setting it up on the IP of 127.0.0.1<\/p>\n Now, assuming we’re already logged into WHM, we can enter that command in our browser – you should receive JSON output that looks similar to the following, but depending on your browser this could be all displayed on one line.<\/p>\n In general, when working with JSON, “1” indicastes positive output, meaning the action completed successfully. We can see from this output that the domain was accepted and example.com has been created on the server. If we check out WHM >> Edit a DNS Zone you should see example.com in your list now, and selecting it will show a zone file with all the default cPanel records:<\/p>\n Using Custom Code for API Calls<\/b><\/span><\/p>\n The second way to interact with the cPanel API is to call the API functions through custom code. When writing your own code there are many options limited only by your creativity. The examples here are just that – examples to show you the basics so you can see how the API code functions within a Perl script. They are by no means exhaustive in any way.<\/p>\n Prerequisites<\/span><\/b><\/p>\n Since this code will be called from a file we need to have a way to interact with WHM so we use an access hash so our commands are authenticated just as if we were clicking items in the WHM interface. An access hash is a way for a program to access a server without having to use the root password. This hash is used for several things in the cPanel system, most notably setting up DNS Clusters. To create this hash you can visit WHM >> Remote Access Key. There is likely a key already in place on your server – if this is the case it’s best to just use what already exists. If there isn’t a key in place you can generate one with the blue “Generate New Key” button on the right.<\/p>\n That long string of text is what we’ll need to use in our file. You can also find that at \/root\/.accesshash. We’ll need to add that block to line 14 of the code in the example below.<\/p>\n Since we’re working with Perl we’ll also need some of the standard Perl modules installed on the server. You’ll want to run the following two commands to get these modules installed:<\/p>\n Building the Code<\/span><\/b><\/p>\n Now that we have the access hash we can use that in our code to authenticate our script to make an API call. Just like in our first example, here is some code that will create a DNS zone for example2.com. I’m using example2.com since we already created example1.com in our previous test. You can copy and paste the following code into a file named dns-example.pl using your favorite text editor. The file is named with the “.pl” extension because it is a Perl script. It looks like there is a large amount of code necessary to create a DNS zone, but much of this is just the access hash.<\/p>\n When you go to use this code you’ll need to replace lines 14-42 with your own access hash. There are also ways to have the script read the access hash directly from the server but that level of programming is beyond the scope of this guide.<\/p>\n To better understand what is happening in this code, here is a line-by-line description:<\/p>\n Lines 1-48: Creates the user agent and declares variables, including the access hash You’ll also need to make sure the script has executable permissions so it can run on the server. After you’ve saved the file with all of your changes you can issue the following command from shell to change the permissions so the script can be executed<\/p>\n If this code were being used in a production environment the “&domain=example2.com” and the “&ip=127.0.0.1” sections would ideally be variables that get their values from data entered by a user through some type of form. However, since we’re just providing an example of how the code works outside of a working graphical interface they’ll need to be hard-coded.<\/p>\n Executing the Script<\/span><\/b><\/p>\n Once you have the file saved you can execute it by running the following command: If everything goes well you should get output that looks similar to the following:<\/p>\n![\"WHM_API_1_breakout\"](\"http:\/\/blog.cpanel.com\/wp-content\/uploads\/2014\/12\/WHM_API_1_breakout-300x48.png\")
<\/a><\/p>\n
\nThe following methods assume you’re already logged in to WHM as root and have a security token. This means that you’ll have a unique, 10-digit session ID in the format of https:\/\/x.x.x.x:2087:cpsess##########<\/a>. In the following examples I’ll just use the localhost IP of 127.0.0.1 and cpsess########## to avoid confusion so be sure to edit these commands with the appropriate details for your own server if you want to try these out for yourself.
\n**********<\/p>\nhttps:\/\/127.0.0.1:2087\/cpsess##########\/json-api\/adddns?api.version=1&domain=example.com&ip=127.0.0.1<\/pre>\n<\/div>\n
{\n metadata: {\n result: 1,\n version: 1,\n reason: 'Added example.com ok belonging to user root',\n command: 'adddns'\n }\n}<\/pre>\n<\/div>\n![\"example1_adddns\"](\"http:\/\/blog.cpanel.com\/wp-content\/uploads\/2014\/12\/example1_adddns-300x150.png\")
<\/a><\/p>\n![\"access_hash\"](\"http:\/\/blog.cpanel.com\/wp-content\/uploads\/2014\/12\/access_hash-300x179.png\")
<\/a><\/p>\nyum install perl-XML-Simple\n\/scripts\/perlinstaller LWP::Protocol::https<\/pre>\n<\/div>\n
#!\/usr\/bin\/perl\nuse strict;\nuse warnings;\nuse LWP::UserAgent;\nuse XML::Simple;\nuse Data::Dumper;\nuse HTTP::Cookies;\n \n$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;\n \nmy $hostname = 'localhost';\nmy $protocol = 'https';\nmy $accesshash = <<'END';\na1afa058158ada545f9cd9c0bb3cde63\n0baa595074c2e42e2f8513103688eb6c\nbb6c343a05826b6b6e300b77e566b876\nde4c14ad947efc3d27566c5bc69caeea\n4edcb02301fb87b49bcf2e7ccfb4184a\nb42b83f41ded645c7c9061ab369bddc9\nc786062777d7832e123a8334f56aef3e\n4388f368249022cabde665d7261ab88a\n70d030daefafdaead1ce815e98558d6c\ncb7bbc1052a60df4ed110e0c0f909bd6\nefc43e9923542e290fc6209d038adae9\nbee24339bf9d849fcd78c50d29474193\ndfeb9de9f979cb06e90d3d66b618369d\n180ae4382550a177316f872254739990\n8b5de8ab871029a47f29ccd90ee5e52f\nb12bf41f37de3ead8cdd26027d50364d\n1a6df8c0f2d29ecd29aab9254eeb6808\nd232f1e729453a5a5de27e276e9bba1d\n8a27ba0d4690af299d4e461757bfa412\n1a0bb3474b46d14926ff7351a1d2d550\nb19351d670c82c82cfdf661ed7effc8d\n530af69720062aa62e48ea5c45261691\nd2c49b4def5f2e47beac5f796304a024\n4ecb921948a8c77c00d78a4fee6e8743\n7430731106a8f56e2853798533672868\nd92f2eb9b9444492ac2701f1367e0b9f\n843078ac419a2e6a90342848f756edde\n1dfb59a5fdfed2ad8954ec3c2ee7b868\n2c9aa7f30d722a566d755b54778c6a96\nEND\n$accesshash =~ s\/n\/\/g;\nmy $useragent = LWP::UserAgent->new(\ncookie_jar => HTTP::Cookies->new,\n);\n$useragent->default_header( 'Authorization' => \"WHM root:$accesshash\" );\n my $url = \"$protocol:\/\/$hostname:2087\/json-api\/adddns?api.version=1&domain=example2.com&ip=127.0.0.1\";\n my $response = $useragent->get($url);\n my $response_data = $response->decoded_content;\n print $response_data;<\/pre>\n<\/div>\n
\nLines 49-51: The actual API code
\nLine 52: The output from the code<\/p>\nchmod 755 dns-example.pl<\/pre>\n<\/div>\n
\n\/usr\/bin\/perl dns-example.pl<\/p>\n
![\"example_output\"](\"http:\/\/blog.cpanel.com\/wp-content\/uploads\/2014\/12\/example_output-300x7.png\")
<\/a><\/p>\n![\"final_zone\"](\"http:\/\/blog.cpanel.com\/wp-content\/uploads\/2014\/12\/final_zone-300x179.png\")
<\/a><\/p>\n