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:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
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