Simple API Writing, Part I
Posted by Nessa | Tags: cpanel,php,tutorials | Posted on 02-09-2009
6
A lot of people don’t realize how easy it is to write an API with PHP. It really is as easy as having a simple PHP script accepting GET variables, and when you add in some security, you can pretty much do anything you want with a single script that accepts variables from any authenticated source. So a little while ago I posted about the new cPanel XML API and how to integrate that with your own scripts – well now, I’ll use that as an example to show you how to write an API for their API, a.k.a, an API connector. Though in real applications you wouldn’t need an API, all you’d need is a PHP script that accepts GET or POST input to perform some kind of action. In this example, we’ll have a script that automatically adds DNS zones to a nameserver that runs cPanel as well.
Most APIs do the same thing – you have a script, then that script accepts post/get variables, then does something.
The Interface (addzone.php):
You guy remember the one I posted a while back – well, we’ll use the same one only a tad different. This is the script that runs statically on the server, which accepts the variables passed through the URL:
// API for adding a DNS zone to ns cluster
$isinclude = “1″; // specifies $isinclude for xmlapi.php
// GET & POST definitions
$key = “098f6bcd4621d373cade4e832627b4f6″;
$domain = $_GET['domain'];
$ip = $_GET['ip'];
// Validation – make sure that we have the right information
if($_POST['key'] != $key){ echo “Invalid key!!”; die(); }
if(empty($domain)){ echo “Domain value missing!!”; die(); }
if(empty($ip)){ echo “IP Value missing!!”; die(); }
$theServer = “ns1.v-nessa.net”; // the server to connect to
$apiPath = “/xml-api/adddns?domain=$domain&ip=$ip”; // the xml api path
$user = “root”; // use to connect to whm as
// ns1 hash (whm > remote access)
$rhash = “e9917f16b3fda69137192725a06b68e7
230e99fd445473807e33d637878641a5
–edited out for sake of length–
f673567ab443acedc77f9aec62ff953f”;
// Include the API connector
include(“xmlapi.php”);
// Output XML Result
$xmlObject=simplexml_load_string($xmlresult);
echo $xmlObject->result->statusmsg . “\n”;
?>
The file that is called via include() is the basic xml function file which constructs all of the variables from the outser script (shown above). You can get a copy of of xmlapi.php from here, but for this example you need to comment out the output.
Now all we need to do is pass the variables that the script needs in order to know what information to process, which is $ip and $domain. Therefore, in order to successfully call this API, you would enter the following in a browser:
http://v-nessa.net/api/addzone.php?domain=test.v-nessa.net&ip=205.134.252.71
This will pass the ‘domain’ and ‘ip’ variables to addzone.php, which uses the XML API to connect to WHM and add a dns zone on the nameserver ns1.v-nessa.net. This is a problem though – what’s to keep outsiders from finding this and abusing it? Well, there are several forms of non-interactive authentication you can use, such as:
- Have an allow list of ips that can access the script (look up environmental variables at php.net)
- Requiring a key or token
I generally use a key, though there are better ways to do this. The way I’m about to show you is simple and secure, but slightly limits the way your API can be called.
First, I generated an md5 hash and defined it in the scipt (remember $key = “098f6bcd4621d373cade4e832627b4f6″; ?). Then all I need to do is make sure that key is used whenever I call the API. Notice that in addzone.php it’s defined as a POST variable? That is mainly for preference but you can just as easily make it a GET variable and just add it to your URL line. Here I want it to be posted, so I can call the API through cURL as follows:
curl -k http://v-nessa.net/api/addzone.php?domain=test.v-nessa.net&ip=205.134.252.71 -d key = “098f6bcd4621d373cade4e832627b4f6
And there you have it! A very simple way to write an API using POST and GET.
