Here's an equation that should work better, but at the moment, doesn't:

To put it simply, there's a lot of room for improvement when it comes to PHP code libraries for Tucows' various APIs, and it's high time that those improvements were made. That's what this post is about — my plans to rectify the situation.

The Current Client Code Situation

There are two official pieces of client code, each of which addresses a different need:

• The Reseller Client Library (RCL): Our original client code. Written in Perl, this is a library upon which you can build a client application that makes use of the XCP and TPP protocols (which in turn means that you can provision every major Tucows service with the exception of Blogware). Intended primarily for developers, it's just a skeleton — you can't just upload it to a server, set a configuration file and have a website up and running. You have to do some coding first.
• The Client Code Suite (CCS): Our new client code. Written in PHP 5, this is a complete application that's ready to run once you've run the setup programs and added your own branding. It's capable of provisioning domains for the more popular TLDs, Blogware and Blogware/domain name bundles. It also ties in very nicely with our Platypus billing system.

What's missing is some client code that serves the people in the middle ground between the RCL and CCS — a Tucows API library that is both:

• Written in PHP
• A library that can be integrated into your code

My plan to bring such a library into existence as soon as possible.

The Good News: The Hard Part has Already Been Done!

Colin Viebrock, who used to work in Tucows' Content division, wrote a PHP library for making API calls to OpenSRS a few years ago. His SourceForge-hosted library, called PHP OpenSRS Client, simplifies making XCP and TPP calls and takes care of the little authentication dance you must do in order to connect to the server. It hasn't been updated in a while, but there hasn't been any need to do so: it works, and better yet, it works under both PHP 4 and PHP 5.

I've used Colin's library for a number of small projects, the most recent of which was the Duke of URL application: it uses the library to make and get the return value of the newly-minted XCP API call NAME_SUGGEST.

The Bad News: Little Documentation, A Little Tricky to Use

The library comes with only a little documentation, and as an unofficial project, there are no code examples for it in the the official Tucows API docs. Those API docs provide Perl (under the RCL) and XML example, but not PHP (under the PHP OpenSRS Client). If you're a programmer who's planning on using the OpenSRS PHP library, you're going to have to do some reverse engineering and endure a little some trial-and-error.

Here's an example: let's say you want to ask the live server (as opposed to the test server, a.k.a. “Horizon”) suggestions for available .com, .net and .org domain names based on the word “steak”.

The docs provide examples of how to make this call using raw XML and Perl (with the RCL), but don't explain how to do so with PHP and the PHP OpenSRS Client. Wouldn't it be nice if the official docs told you that the following PHP code, in conjunction with the PHP OpenSRS Client, would do the trick?

$srs = new openSRS($'live', 'XCP'); 
$cmd = array(
    'action'     => 'NAME_SUGGEST',
    'object'     => 'domain',
    'attributes' => array(
        'searchstring' => 'steak',
        'tlds'         => array('.com', '.net', '.org')
    ));
$result = $srs->send_cmd($cmd);

Let's improve on the scenario a little more. Wouldn't it be even nicer if there was a PHP library that wrapped the OpenSRS functions so that instead of having to write all the code above, you could make a call to a function whose signature was:

nameSuggest($searchTerm, $tlds, $server)

These are things I'd like to see.

The Plan

I think that having both documentation that included PHP examples and a library of functions that wrapped our APIs would make a big difference to a lot of people who use our services. The problem is that our developers have their hands full with large projects.

That's where I come in. Part of my job description as Tucows' Technical Evangelist is to make it easier for developers to integrate their projects with Tucows' services. Writing the extra documentation and the wrapper library easily falls under that description, and it'll also give me some more stuff to write about in this blog.

I've got some stuff to wrap up by the end of this week, but on Monday, I shall begin the process of putting together the wrapper library, and the documentation shall be based on it. I'll chronicle my progress here on the Tucows Blog. As the work progresses, your input is most welcome, whether in the form of questions, comments or even code.

Got any questions, opinions or suggestions on this plan? Let me know in the comments!

Posted on Wednesday, January 31st, 2007 at 9:23 pm by Tucows.
Filed under: Programming.
Both comments and pings are currently closed.