Work on Project Ash, my project to develop PHP libraries to access the Tucows APIs, is progressing and picking up speed. While working on it, I thought I'd share my general design principles for Project Ash with you…

Compatibility with both PHP 4 and 5.

This is an important stipulation: a number of our partners are sticking with PHP 4 so as not to break PHP 4-based applications on which both they and their customers rely. Although I will be building the libraries in PHP 5 to take advantage of some development niceties such as the use of the PHPUnit unit testing framework, I'm targeting PHP 4. I'll write the code in such a way that it will run under PHP 4 and will test on a PHP 4-equipped computer.

Input as Simple as Possible, But No Simpler

When you make API calls using the libraries, it should be a simple as calling a method or function and providing parameters through its arguments. For example, a call to the function that wraps the API call to the live server for the lookup domain for the domain example.com should look something like this:

$result = lookup_domain('live', 'example.com');

and not like this:

$params = array('server' => 'live',                'domain' => 'example.com');$result = lookup_domain($params);

Output as Simple as Possible, But No Simpler

Some of the Tucows APIs return large data structures which often contain redundant information, such as the way the XCP API returns both a numeric and text response code (the text response code is good for debugging, however). Some of these structures are deeply nested. The Ash libraries will be designed so that any output they produce will have no redundant information and will be as “shallow” as possible.

Plain Old Functions, When They Make Sense

Although the object-oriented programming is a great organizational technique for software, I'm don't think that it's the be-all and end-all of programming.

Consider the Lookup Domain API call, which accepts a domain name and returns a value that indicates whether it's available: for such a simple action, I don't think there's any need to instantiate a class just to make this call. Why not simply call a function called lookup_domain()?

Classes, When They Make Sense

Other calls, such as SW Register Domain require a lot of setup in the form of a large number of parameters, some parameters may depend on others and some business logic may be required. In such cases, using classes to manage the complexities of these API calls makes sense.

No “Magic Numbers”

Many Tucows API functions return numeric result codes. In order to reduce the likelihood of programming errors and help you make your client code more readable, the libraries will come with a large number of predefined constants for result codes so you won't have to memorize that 210 means “Domain available” and 211 means “Domain taken”.

A Step Towards a Mashable Future

Project Ash should be the first step towards a “mashable future” for the Tucows APIs, one in which it should be easy to a developer to incorporate Tucows services into his or her own applications. Rather than handing out large monolithic clients that are difficult to customize for your business, I'd like to see little pieces that are easy to plug into your existing and future projects.

Posted on Monday, February 26th, 2007 at 6:48 pm by Tucows.
Filed under: Programming.
Both comments and pings are currently closed.