The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Domain-Register-TK.2.1
River stage zero No dependents
++
/ Domain::Register::TK

NAME

Domain::Register::TK - an interface to Dot TK's Reseller API Program

VERSION

Version 2.1

SYNOPSIS

This module allows developers to create and maintain domains within the .TK name space, using Dot TK's reseller program API, without having to know the details of how the API program works. Domains can be checked (with price provided in local currency) and updated, including using URL forwarding services, or manipulating nameserver references

DESCRIPTION

Dot TK has an extensive Application Programming Interface (API) that allows you to administer your domains simply and effectively. Designed for large portfolio resellers, the Dot TK API will allow you to automate functions and reduce the time needed to manage your Dot TK Reseller account.

This version of the Dot TK API allows you to use the API as a Perl library without needing to understand the complexities of the regular API. This document, however, just handles the Perl library for this API. For more complete documentation of the functions, see the main API documentation.

DEPENDENCIES

This module relies on XML::Simple and LWP. In addition it requires that LWP be installed with an additional library to handle secure connections. OpenSSL or Crypt::SSL are suggested as possibilities.

SUBROUTINES/METHODS

An object of this class represents a potential dialogue with Dot TK's servers, and as such needs correct log in credentials to do anything useful.

Standard usage is to create an object, supply that object with log in credentials, and perform an arbitrary number of transactions with the remote server. There is a ping transaction which does not require parameters, that should be used to test if a connection is still possible. It is possible to change credentials after some operations (if, for example, different currencies were being used for different end-users) without having to create a new object.

No state is saved by the remote server between transactions, so it is not necessary to log on or log off separately, as long as valid credentials are supplied.

Setting Up

Simply create an object from the library, and pass the email address and password of your reseller account to it.

 use Domain::Register::TK;
 my $api_object = Domain::Register::TK->new();
 $api_object->credentials('login@email.com', 'mypassword');

General error handling

Every request made after setup will return values, in addition to setting internal variables to hold the status (accessible via functions)

 # for example (more details on this operation later)
 $api_object->availability_check('DOT.TK');
 print $api_object->status . ' - ' . $api_object->errstr;

The function status will either return OK or NOT OK. If a request was able to be processed successfully; it will have a status set to OK. This does not mean that the request was processed (for example, if registering a domain that was not available), just that enough information was passed that it could have been. If the status is NOT OK there will be a detailed reason in the errstr function, which otherwise will be undef.

The values returned will be in form of a reference to an associative array, with contents depending on the function involved.

Proxy

Function: proxy

Parameters: URL

If you need to use a proxy server to be able to access the Dot TK server on the internet, it can be specified here. It should be in the form of a URL, with the port number to use.

 $api_object->proxy('https://192.168.10.1:443');

No response is given to this function, it simply sets a value that can be used by other operations

Set Timeout

Function: set_timeout

Parameters: TIME_IN_WHOLE_SECONDS

By default, requests will return, giving an error state if there has been no response from either the supplied proxy, or the Dot TK servers, in 15 seconds. If you want to change this, pass in the required time, in seconds.

Ping

Function: ping

Parameters: none

 $result_code = $api_object->ping();

Possible response:

 $result_code = {
          'timestamp' => '2009-07-28 14:10:28 UTC',
          'status' => 'PING REPLY',
          'type' => 'result'
        };

Availability Check

Function: availability_check

Parameters (all compulsory): DOMAIN-NAME.TK, PERIOD_IN_YEARS

 # an example
 my $return_value = $api_object->availability_check('TESTDOMAIN-0001.TK',1);

Possible responses are:

 # if available to be registered, this is what the return value would look like
 $return_value = {
          'partnerrate' => '4.50',
          'status' => 'AVAILABLE',
          'retailrate' => '9.95',
          'domainname' => 'TESTDOMAIN-0001.TK',
          'currency' => 'GBP',
          'lengthofregistration' => '1',
          'type' => 'result',
          'domaintype' => 'PAID'
 };

or

 # if already registered:
 $return_value = {
          'status' => 'NOT AVAILABLE',
          'lengthofregistration' => '1',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0002.TK',
          'expirationdate' => '20100225'
        };

Domain Registration

Function: register

Parameters: (compulsory) DOMAIN-NAME.TK, PERIOD_IN_YEARS

Parameters: (optional) either an array reference of name servers, or a URL for forwarding, or no parameter

 # with an array of name servers
 $return_value = $api_object->register('TESTDOMAIN-0003.TK', 1, ['NS1.A.COM.TK', 'NS2.A.COM.TK']);

or

 # with a URL for forwarding
 $return_value = $api_object->register('TESTDOMAIN-0004.TK', 1, 'http://www.icann.org/');

or

 # with unused (can be set later, or just protected from other potential uses)
 $return_value = $api_object->register('TESTDOMAIN-0005.TK', 1);

Possible responses:

 $return value = {
          'partnerrate' => '4.50',
          'status' => 'REGISTERED',
          'retailrate' => '9.95',
          'domainname' => 'TESTDOMAIN-0004.TK',
          'expirationdate' => '20100724',
          'currency' => 'GBP',
          'lengthofregistration' => '1',
          'type' => 'result'
        };

or

 # if already registered:
 $return_value = {
          'status' => 'NOT AVAILABLE',
          'lengthofregistration' => '1',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0002.TK',
          'expirationdate' => '20100225'
        };

Renewal of Domains

Function: renew

Parameters: (compulsory) DOMAIN-NAME.TK, PERIOD_IN_YEARS

 $return_value = $api_object->renew('TESTDOMAIN-0001.TK', 3);

Possible responses:

 # if supplied domain is available
 $return_value = {
          'partnerrate' => '13.5',
          'status' => 'RENEWED',
          'retailrate' => '24.75',
          'domainname' => 'TESTDOMAIN-0001.TK',
          'expirationdate' => '20120723',
          'currency' => 'GBP',
          'lengthofregistration' => '3',
          'type' => 'result'
        };
 
 # if domain is not available
 $return_value = {
          'domainname' => 'TESTDOMAIN-0002.TK',
          'lengthofregistration' => '3',
          'status' => 'NOT AVAILABLE',
        };

Add/modify glue record

Function: host_registration

Parameters: HOSTNAME, IPADDRESS (both are compulsory)

 $return_value = $api_object->host_registration('NS1.TESTDOMAIN-0005.TK','192.168.1.22');

Possible responses:

 $return_value = {
          'status' => 'REGISTERED',
          'type' => 'result',
          'hostname' => 'NS1.TESTDOMAIN-0005.TK',
          'ipaddress' => '192.168.1.22'
        };
 # or if this name has already been used as a glue record
 $return_value = {
          'status' => 'UPDATED',
          'type' => 'result',
          'hostname' => 'NS1.TESTDOMAIN-0005.TK',
          'ipaddress' => '192.168.1.22'
        };

This routine will use standard error messages if you attempt to add glue records to domains not in your portfolio.

Remove glue record

Function: host_removal

Parameters: HOSTNAME (compulsory)

  $return_value = $api_object->host_removal('NS1.TESTDOMAIN-0005.TK');

Possible responses

 $return_value = {
          'status' => 'REMOVED',
          'type' => 'result',
          'hostname' => 'NS1.TESTDOMAIN-0003.TK'
        };

List glue records

Function: host_list

Parameters: DOMAIN (compulsory)

 $return_value = $api_object->host_list('TESTDOMAIN-0003.TK');

Possible responses:

 $return_value = {
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0003.TK',
          'host' => [
                    {
                      'hostname' => 'NS3.TESTDOMAIN-0003.TK',
                      'ipaddress' => '192.168.0.11'
                    },
                    {
                      'hostname' => 'NS2.TESTDOMAIN-0003.TK',
                      'ipaddress' => '192.168.20.254'
                    },
                    {
                      'hostname' => 'NS4.TESTDOMAIN-0003.TK',
                      'ipaddress' => '192.168.1.1'
                    },
                    {
                      'hostname' => 'NS1.TESTDOMAIN-0003.TK',
                      'ipaddress' => '192.168.10.1'
                    }
                  ]
        };

Update domain DNS

Function: UPDATEDNS

Parameters: DOMAIN (Compulsory)

Parameters: (optional) either an array reference of name servers, or a URL for forwarding.

 # with an array of name servers
 $return_value = $api_object->updatedns('TESTDOMAIN-0003.TK', ['NS1.A.COM.TK', 'NS2.A.COM.TK']);

or

 # with a URL for forwarding
 $return_value = $api_object->updatedns('TESTDOMAIN-0004.TK', 'http://www.icann.org/');

Possible response (regardless of form used):

 $return_value  = {
          'status' => 'NAMESERVERS UPDATED',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0004.TK'
        };

Update WHOIS information

Function: updatewhois

Parameters: (compulsory) DOMAIN, HASHREFENCE of keys to change

This function is called a little differently from everything else. Instead of passing a large number of parameters in a fixed order, it requires a Hash Reference to a collection of key->value pairs representing the items in the WHOIS record that are to be changed.

The keys the system recognizes are those mentioned in the main API documentation under updatewhois, except function, email and password.

For example:

 $result_code = $api_object->updatewhois('TESTDOMAIN-0003.TK', {reg_company => 'Dot TK BV', reg_city => 'Amsterdam', reg_countrycode => 'NL'});

Possible response:

 $result_code = {
          'status' => 'WHOIS INFORMATION UPDATED',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0003.TK'
        };

Domain Status

Function: domain_status

Parameter: (compulsory) DOMAIN

 $result_code = $api_object->domain_status('TESTDOMAIN-0003.TK');

Possible response:

Depending on the relation between Reseller and Domain, there can be three different types of output:

If the domain is available for registration

 $ result_code = {
          'status' => 'AVAILABLE',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0003.TK',
          'pricing' => [
                       {
                         'currency' => 'GBP',
                         'retailprice' => '19.90',
                         'partnerprice' => '9.00',
                         'lengthofregistration' => '2'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '24.75',
                         'partnerprice' => '13.50',
                         'lengthofregistration' => '3'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '31.80',
                         'partnerprice' => '18.00',
                         'lengthofregistration' => '4'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '37.50',
                         'partnerprice' => '22.50',
                         'lengthofregistration' => '5'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '62.55',
                         'partnerprice' => '40.50',
                         'lengthofregistration' => '9'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '9.95',
                         'partnerprice' => '4.50',
                         'lengthofregistration' => '1'
                       }
                     ],
          'domaintype' => 'PAID'
        };

If the domain is registered, but not part of the domain portfolio of the reseller that uses this query

 $result_code = {
          'whois_info' => {
                          'reg_name' => 'Ccops Center',
                          'reg_address' => 'PMB 155, 10400 Overland Road',
                          'reg_zipcode' => '83709',
                          'reg_statecode' => 'US-ID',
                          'reg_countrycode' => 'US',
                          'reg_company' => 'eMarkmonitor Inc',
                          'reg_email' => 'ccopsbilling@markmonitor.com',
                          'reg_fax_nr' => '208-3895799',
                          'reg_city' => 'Boise',
                          'reg_phone_nr' => '208-3895740'
                        },
          'status' => 'NOT AVAILABLE',
          'type' => 'result',
          'nameservers' => [
                           {
                             'hostname' => 'NS1.GOOGLE.COM'
                           },
                           {
                             'hostname' => 'NS2.GOOGLE.COM'
                           },
                           {
                             'hostname' => 'NS3.GOOGLE.COM'
                           },
                           {
                             'hostname' => 'NS4.GOOGLE.COM'
                           }
                         ],
          'domainname' => 'GOOGLE.TK',
          'expirationdate' => '99999999'
        };

If the domain is registered and is part of the domain portfolio of the reseller that uses this query

 $result_code = {
          'whois_info' => {
                          'reg_name' => 'Dot TK Reseller',
                          'reg_address' => '8 Berwick Street',
                          'reg_zipcode' => 'W1F 0PH',
                          'reg_countrycode' => 'GB',
                          'reg_company' => 'Dot TK plc',
                          'reg_email' => 'partners@dot.tk',
                          'reg_fax_nr' => '2077349597',
                          'reg_city' => 'London',
                          'reg_phone_nr' => '2077349596'
                        },
          'status' => 'NOT AVAILABLE',
          'type' => 'result',
          'nameservers' => [
                           {
                             'hostname' => 'NS1.A.COM.TK',
                             'ipaddress' => {'192.168.0.1'}
                           },
                           {
                             'hostname' => 'NS2.A.COM.TK',
                             'ipaddress' => {'192.168.202.1'}
                           }
                         ],
          'domainname' => 'TESTDOMAIN-0003.TK',
          'expirationdate' => '20100723',
          'pricing' => [
                       {
                         'currency' => 'GBP',
                         'retailprice' => '19.90',
                         'partnerprice' => '9.00',
                         'lengthofregistration' => '2'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '24.75',
                         'partnerprice' => '13.50',
                         'lengthofregistration' => '3'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '31.80',
                         'partnerprice' => '18.00',
                         'lengthofregistration' => '4'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '37.50',
                         'partnerprice' => '22.50',
                         'lengthofregistration' => '5'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '62.55',
                         'partnerprice' => '40.50',
                         'lengthofregistration' => '9'
                       },
                       {
                         'currency' => 'GBP',
                         'retailprice' => '9.95',
                         'partnerprice' => '4.50',
                         'lengthofregistration' => '1'
                       }
                     ],
          'domaintype' => 'PAID'
        };

Generate authorization code

Function: generate_authcode

Parameters: DOMAIN (compulsory) - the domain to generate the code for

 $api_object->generate_authcode('TESTDOMAIN-0001.TK');

Possible response:

 # if successful
 $VAR1 = {
          'authcode' => '1234567890123456',
          'status' => 'AUTHCODE GENERATED',
          'type' => 'result',
          'domainname' => 'TESTDOMAIN-0001.TK'
        };

Price Transfers

Function: price_transfer

Parameters: DOMAIN, AUTHCODE (both compulsory)

 # in receiving account
 $result_code = $api_object->price_transfer('TESTDOMAIN-0001.TK', '1234567890123456');

Possible response:

 $result_code = {
          'partnerrate' => '2.00',
          'status' => 'RATES PROVIDED',
          'retailrate' => '12.50',
          'domainname' => 'TESTDOMAIN-0001.TK',
          'currency' => 'YTL',
          'lengthofregistration' => '1',
          'type' => 'result',
          'domaintype' => 'PAID'
        };

Transfer of domains

Function: transfer

Parameters: DOMAINAME, AUTHCODE

 # again, in receiving account
 $result_code = $api_object->transfer('TESTDOMAIN-0001.TK', '1234567890123456');

Possible response:

 $result_code = {
          'partnerrate' => '2.00',
          'status' => 'TRANSFERRED',
          'retailrate' => '12.50',
          'domainname' => 'TESTDOMAIN-0001.TK',
          'expirationdate' => '20110731',
          'currency' => 'YTL',
          'lengthofregistration' => '1',
          'type' => 'result'
        };

AUTHOR

Dot TK Reseller API Program <partnerapi at dot.tk>

Please report any bugs or feature requests to bug-domain-register-tk at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Domain-Register-TK.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Domain::Register::TK

You can also look for information at:

COPYRIGHT

Copyright (c) 2010 Dot TK Ltd. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License", that is, the same terms as Perl itself.

This module requires that the client user have an active account with Dot TK http://www.dot.tk in order to access it's key functionality