Coding the Duke #2: A Simple Domain Lookup
Welcome to Coding the Duke, a series of articles that looks at the code behind the Duke of URL application and the development of OpenSRS clients in PHP using the OpenSRS-PHP library. In this second installment, I'm going to talk about OpenSRS, Tucows APIs, XCP and finally walk you through a very small app that checks a domain name for availability.
Make sure you've read the first article in this series, Coding the Duke #1: Introducing OpenSRS-PHP. It covers the OpenSRS-PHP library, which you need to try out the code examples in this and future articles.
A Little Background (or: “What is OpenSRS, Anyway?”)
If you downloaded the Duke of URL code that I posted online last week, you'll have noticed that it's largely concerned with providing a user interface. The real heavy lifting is done by OpenSRS, which is accessed by through an API call, and that API call is made with the help of the OpenSRS-PHP library.
The question that naturally comes to mind is: What is OpenSRS, anyway?
First, let's get some terminology straight. In the process of registering domain names, there are three players:
- Registrant: the person or organization who wants to register one or more domain names.
- Registry: the authoritative system that keeps track of domain names for a given top-level domain (TLD) and the information required to resolve them. There's a registry for each TLD; that is, there's a registry for .com names, one for .org names, and so on.
- Registrar: a approved organization that acts as a go-between for the registrant and the registry.
Since the system of domain names is a vital part of the internet, it was decided that the ability to access the various domain name registries had to be limited to a relatively small set of trusted parties: the registrars. Rather than boring you with the details, I'll simply say that becoming a registrar requires a lot of paperwork, some money and doing the necessary legwork and schmoozing to get ICANN's blessing.
(If you're really curious, you can check out ICANN's list of accredited registrars.)
While keeping the ranks of the registrars limited to a select group has its advantages, it's not all that good for a lot of people who have good reasons to offer domain name registration services, such as ISPs and hosting companies, who want to be able to package a domain name along with their access and hosting offerings, web application vendors who want to offer their customers personalized portals, or people who just want to get into the domain business but don't have the connections or cash to be accredited by ICANN. If you were one of these people or were in a similar situation, the only way you could register domain names was by dealing with the customer-facing part of a registrar…until 1999.
In the fall of 1999, Tucows launched OpenSRS, short for Open Shared Registration System. Tucows was a registrar, but rather than going into the business of retailing domain names, went into the business of selling the capability to sell domain names. Anyone who signed up to become a Tucows reseller could get into the domains business. Tucows became a domain name wholesaler, and our partners became domain name retailers.
As time passed, we found that a lot of our domain name partners wanted to be able to reseller other services too, so we added them: email, anti-spam, digital certificates and so on. These other services, while not having anything to do with registration, were offered in a similar manner, and thus fell under the OpenSRS umbrella. These days, OpenSRS refers to more than just the domain name wholesale service, but the following services in the Tucows platform:
Tucows Protocols
The ways in which you can provision and manage Tucows' services fall into two major categories:
- Using the web-based control panels
- Using the APIs
The web-based control panels are simple to use are require no setup or programming on your part. However, this simplicity comes at a cost: a real live human being has to sit at a computer and provision and manage service manually. This is good in simple cases, but if you want to set up a web site that customers can use to buy domains, email or other services whenever they want, you're going to want to use those APIs.
Over the years, as Tucows has added services to its platforms, it has also added a number of API protocols to provision and manage those services. Here are the three big ones:
- XCP: Short for eXternal Client Protocol. This is the original API and is used to provision and manage domain names.
- TPP: Short for Tucows Provisioning Protocol. Also referred to as “Tulips”. This API is used to provision email, Email Defense, Digital Certificates, Managed DNS and Website Builder.
- Blogware Provisioning Protocol: This is used by Blogware resellers to provision and manage their customers' blogs.
Over the coming year, I'll be writing articles on how to utilize these APIs. For now, I'll be concentrating on domain name operations, which means using focusing on XCP.
Getting the XCP Documentation
All of the documentation for Tucows' services can be found on our documentation site at documentation.tucows.com. XCP is very thoroughly covered in the OpenSRS API Specification [1.5 MB PDF].
A Dirt Simple OpenSRS-PHP Application
I figure I've bored you with enough prologue, so how 'bout some actual coding?
The best way to get familiar with building OpenSRS client applications in PHP using the OpenSRS-PHP library is to put together a simple application. The one that I'm about to show uses only a few lines of code, requires simple input and produces simple output.
We'll make use of XCP's LOOKUP DOMAIN call. It does what its name implies: given a domain name, it returns a response that says whether or not it's available.
Here's the code for a simple application built on the OpenSRS-PHP library that uses LOOKUP DOMAIN:
<?php
require_once 'openSRS.php';
$srs = new openSRS('LIVE', 'XCP');
$cmd = array(
'action' => 'LOOKUP',
'object' => 'DOMAIN',
'attributes' => array(
'domain' => 'example.com'
)
);
$result = $srs->send_cmd($cmd);
print_r($result);
?>
Let's go through the code line by line.
require_once 'openSRS.php';
This line implies that you need the OpenSRS-PHP library on your system. For more details on getting it, see the previous article in this series.
$srs = new openSRS('LIVE', 'XCP');
openSRS is a class provided by the OpenSRS-PHP library. It takes the drudgery out of connecting to the OpenSRS servers, dealing with encryption issues and the somewhat strange dialect of XML that the servers speak. With the openSRS class, you're freed from having to parse XML; you're just dealing with good old PHP arrays.
The constructor call for the openSRS class takes two parameters:
| Parameter | What it Does |
|---|---|
| Environment | Specifies which server you're sending OpenSRS API commands to.
This can be set to one of three string values:
|
| Protocol | Specifies which protocol you'll be using.
This can be set to one of two string values:
|
Since we want to check the status of a domain name in the real world, we'll use the live server by setting the environment parameter to the string LIVE. Since this is a domain name operation and the LOOKUP DOMAIN command is in the XCP protocol, we'll set the protocol parameter to the string XCP.
$cmd = array(
'action' => 'LOOKUP',
'object' => 'DOMAIN',
'attributes' => array(
'domain' => 'example.com'
)
);
This line assembles the array that comprises the LOOKUP DOMAIN request. XCP requests, from a PHP programmer's point of view, are an associative array containing another associative array:
| Key | What the Value Does | ||||
|---|---|---|---|---|---|
| action | Specifies the action to take. In the case of LOOKUP DOMAIN, it's the string LOOKUP. | ||||
| object | Specifies the object upon which the action is taken. In the case of LOOKUP DOMAIN, it's the string DOMAIN. | ||||
| attributes | An associative array containing the named parameters for the API call, with each element in the array corresponding to a parameter. In the case of LOOKUP DOMAIN, this is an associative array with a single element whose key is domain and whose value is a string containing the name of the domain we want to check (example.com in this example). Here's what the attributes array looks like in this case:
|
$result = $srs->send_cmd($cmd);
The openSRS class' send_cmd() method is the one that sends the request to the OpenSRS servers and returns the servers' response as its result. As with the request, the result is in the form of an associative array.
print_r($result);
Finally, we print out the result, which should look like this:
Array ( [_OPS_version] => 0.9 [protocol] => XCP [object] => DOMAIN [response_text] => Domain taken [action] => REPLY [attributes] => Array ( [status] => taken [match] => ) [response_code] => 211 [is_success] => 1 )
Here's an illustration of the more important elements of the associative array that you get back:
| Key | What the Value Does | ||||
|---|---|---|---|---|---|
| response_code | An integer that represents the server's response. Response codes fall into these broad categories:
|
||||
| response_text | The English version of the response code. This is subject to change, so if you're testing the server's response, it's generally better to use the response code. | ||||
| is_success | 1 if the operation was performed successfully, 0 otherwise. | ||||
| attributes | An associative array containing any data that might be returned as a result of the operation. In the case of LOOKUP DOMAIN, there's really only one array element we're concerned with: the one whose key is status; its value will be either Available or Taken. Here's what the attributes array looks like in this case:
|
Based on what you've seen here, you should be able to cobble together a user-friendly application that allows users to see if a domain name is available. You should also have a better feel for how to make use of the OpenSRS API Specification.
What's Next
In the next installment, we'll actually make a NAME SUGGEST call, the API call behind the Duke of URL.
