Introduction

The UG Registry API provides an interface that allows registrars create, manage and transfer domains in a simple and automated way. The API complments the NEW registrars' system helping registrars automate and customize some of their functionality.

With the API, authorized registrars will be able to develop applications in their favorite languages that manage domains on the fly.

Update: the url have been updated as of Nov 3, 2017.

Kindly use "https://registry.co.ug" for live api and "https://sandbox.registry.co.ug" for testing.

Prerequisites

In order to access the API, I3C requires the user to be a valid accredited registrar. A registrar is a third party authorized by I3C to manage domains. Find more information about how to become a registrar here.

If you're an authorized registrar, you'll need to configure your API access Information from the registrar's management system. I3C requires registrars to provide the following information:

  1. Login to you registrar account and generate your API credentials and set your API access IPs under the menue Settings > API Settings link.
  2. An auto generated API ID and Password will be provided. You will need these to execute restricted API commands.
  3. You can restrict the IP addreses from which you access the API. These are referred to as "API IP Protection". They are configurable within your registrar account under Settings > API Settings link.

Sandbox Testing Account

The UG Registry API also provides an interface that allows registrars create, manage and transfer domains in a testing enviroment.
The Sanbox accounts exist only in the testing enviroment.

Create your sandbox account at Sandbox Registrar Interface
The Sandbox URL is at https://sandbox.registry.co.ug/api

How the API works

The API works in a simple and straight forward way:

  1. You construct and a send an HTTP POST request to the API server URL: https://registry.co.ug/api. The request contains the command you intend to perform and information required for that command to be successful. The request's contents should be in XML format.
  2. You recieve an HTTP response containing the status and result information of the sent command. This is also in XML format.

The request can be made using any programming langauage by making an HTTP POST to the url "ssl://registry.co.ug/api". Here is an example in PHP programming langauage.

<?php
$url = 'https://registry.co.ug/api';
$headers = array("Content-Type : text/xml", "Content-transfer-encoding : text");
$xml_file_contents = $argv[1]
$request = file_get_contents($xml_file_contents);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    $result = 'ERROR -> ' . curl_errno($ch) . ': ' . curl_error($ch);
} else {
    $returnCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    switch($returnCode){
        case 200:
            break;
        default:
            $result = 'HTTP ERROR -> ' . $returnCode;
            break;
    }
}
curl_close($ch);
$response = new SimpleXMLElement($response);
var_dump($response);
if(property_exists($response, 'success')){
    var_dump($response->success);
}

The Example above assumes that you are passing an xml file as an arguement to the file with contents above. Below is an example that uses an xml string as post data.

<?php
$url = 'https://registry.co.ug/api';
$headers = array("Content-Type : text/xml", "Content-transfer-encoding : text");

$request = '<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="renew">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" period="1" />
</request>'

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    $result = 'ERROR -> ' . curl_errno($ch) . ': ' . curl_error($ch);
} else {
    $returnCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    switch($returnCode){
        case 200:
            break;
        default:
            $result = 'HTTP ERROR -> ' . $returnCode;
            break;
    }
}
curl_close($ch);
$response = new SimpleXMLElement($response);
var_dump($response);
if(property_exists($response, 'success')){
    var_dump($response->success);
}

You can make similar requests in your favourite language for this and subsequent XML requests to be covered.

Reponse on uccess
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="renew" status="1">
    <success code="2" message="Successfully renewed i3c.co.ug" />
    <domain name="i3c.co.ug" status="UNPAID" expiry_date="2016-10-16" />
</response>
Reponse on Failure
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="renew" status="0">
    <errors>
        <error code="1" message="The domain, i3c.co.ug, is not registered to you" />
    </errors>
</response>

Checking Domains availability

You can now use the above XML format to create commands that manipulate domains. Here is the XML request you would post to check availability of a domain . This command can be used to check up to a maximum of 5 domain names.

Check Availabilty Command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="check">
    <domains>
        <domain name="example1.ug"></domain>
        <domain name="example2.ug"></domain>
        <domain name="example3.ug"></domain>
        <domain name="example4.ug"></domain>
        <domain name="example5.ug"></domain>
    </domains>
</request>
Response on Success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response status="1" cmd="check">
    <domains>
        <domain name="example1.ug" avail="1"/>
        <domain name="example2.ug" avail="0"/>
        <domain name="example3.ug" avail="1"/>
        <domain name="example4.ug" avail="0"/>
        <domain name="example5.ug" avail="1"/>
    </domains>
</response>

This command does not require authentication to be successful.

Domain WhoIs Lookup

Use the following command to find out "whois" information for a particular domain.

WhoIs Lookup Command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="whois">
    <domain name="i3c.co.ug" />
</request>
Response on Success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="whois" status="1">
    <success code="2" message="Whois information for i3c.co.ug">
    <domain 
            name="i3c.co.ug" 
            status="ACTIVE" 
            registration_date="2012-02-22" 
            expiry_date="2015-02-22" />
    <contacts>
        <registrant 
            firstname="Charles" 
            lastname="Musisi" 
            email="registrar@i3c.co.ug" 
            organization="Infinity Computers and Communications Company Limited" 
            country="Uganda" 
            city="kampala" 
            street_address="Plot 6b Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="" />
        <admin 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6b Windsor Loop" 
            phone="0312301800" 
            fax="" />
        <tech 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6B Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
        <billing 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6B Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
    </contacts>
    <nameservers>
        <ns1>ns1.cfi.co.ug</ns1>
        <ns2>ns2.cfi.co.ug</ns2>
        <ns3 />
        <ns4 />
    </nameservers>
</response>

This command does not require authentication to be successful.

Registering Domain

There are two commands for registering domains

  • register
  • register_specific

a) register: This command uses the registrar's nameservers and contact details on file as the domain's admin, tech, and billing contact information

Send the following XML command to create the new domain.

register domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="register">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" period="1" />
</request>
          
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="register" status="1">
    <success code="2" message="Successfully registered i3c.co.ug" />
    <domain name="i3c.co.ug" status="UNPAID" expiry_date="" />
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

b) register_specific: This command allows a registrar to specify nameservers and contact Information of the domain's admin, tech, and billing contact

Send the following XML command to create the new domain.

register_specific domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="register_specific">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" />
    <contacts>
        <registrant 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6B Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456" />
        <admin 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6b Windsor Loop" 
            phone="0312301800" 
            fax="" />
        <tech 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="" 
            street_address="" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
         
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6B Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
    </contacts>
    <nameservers>
        <ns1 name="ns1.cfi.co.ug" ip="108.168.172.179" />
        <ns2 name="ns2.cfi.co.ug" ip="174.36.245.66" />
        <ns3 name="ns3.cfi.co.ug" ip="174.36.245.67" />
        <ns4 name="ns4.cfi.co.ug" ip="212.88.97.141" />
    </nameservers>
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="register" status="1">
    <success code="2" message="Successfully registered i3c.co.ug" />
    <domain name="i3c.co.ug" status="UNPAID" expiry_date="" />
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

Ensure to have all required fields populated.

Modifying Domain

Send the following command to update or modify a domain name's nameservers and contacts for which you are a registrar.Leave the fileds you do not want updated empty.

Modify domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="update">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" />
    <contacts>
        <registrant 
            firstname="" 
            lastname="" 
            email="" 
            organization="" 
            country="" 
            city="" 
            street_address="" 
            phone="" 
            fax="" />
        <admin 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6b Windsor Loop" 
            phone="0312301800" 
            fax="" />
        <tech 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="" 
            street_address="" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
        <billing 
            firstname="Charles" 
            lastname="Musisi" 
            email="cmusisi@cfi.co.ug" 
            organization="Infinity Computers and Communications Company" 
            country="Uganda" 
            city="Kampala" 
            street_address="Plot 6B Windsor Loop" 
            phone="+256 31 230 1800" 
            fax="+256 41 434 0456"/>
    </contacts>
    <nameservers>
        <ns1 name="ns1.cfi.co.ug" ip="108.168.172.179" />
        <ns2 name="ns2.cfi.co.ug" ip="174.36.245.66" />
        <ns3 name="ns3.cfi.co.ug" ip="174.36.245.67" />
        <ns4 name="ns4.cfi.co.ug" ip="212.88.97.141" />
    </nameservers>
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="update" status="1">
    <success code="2" message="Successfully updated i3c.co.ug"/>
</response>

The API ID and Password must be provided as shown above for the command to successfully execute. NOTE: Do not supply values for the fields you do not want updated.

Disabling Domain

Send the following command to disable a domain for which you are a registrar.

Disable domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="disable">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" />
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="disable" status="1">
    <success code="2" message="Successfully disabled i3c.co.ug" />
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

Enabling Domain

Send the following command to activate/enable a domain for which you are a registrar.

Enable domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="enable">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" />
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="enable" status="1">
    <success code="2" message="Successfully enabled i3c.co.ug"/>
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

Renewing Domain

Send the following command to renew a domain for which you are a registrar.

Renew domain command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="renew">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" period="1" />
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="renew" status="1">
    <success code="2" message="Successfully renewed i3c.co.ug" />
    <domain name="i3c.co.ug" status="UNPAID" expiry_date="2016-10-16" />
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

Initiating Domain Transfer

Send the following command to initiate transfer of a domain for which you are not a registrar.

Initialize domain transfer command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="request_transfer">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" />
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="request_transfer" status="1">
    <success code="2" message="Request to transfer i3c.co.ug has been processed" />
</response>

The API ID and Password must be provided as shown above for the command to successfully execute.

Complete Domain Transfer

Send the following command to confirm and complete transfer of a domain for which you are a registrar.

complete domain transfer command
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<request cmd="confirm_transfer">
    <auth id="7001107516707" password="2b0335dc6431b985fb706c" />
    <domain name="i3c.co.ug" transfer_id="11" />
</request>
Reponse on success
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<response cmd="confirm_transfer" status="1">
    <success code="2" message="Successfully transfered i3c.co.ug" />
</response>

The API ID and Password and transfer ID (received via email) must be provided as shown above for the command to successfully execute.

More Information

When a command is not successful, several other responses may be returned depending on the cause of failure.