view release on metacpan or  search on metacpan

lib/Domain/Register/TK.pm  view on Meta::CPAN

package Domain::Register::TK;

use strict;
use warnings;

=head1 NAME

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

=cut

our $VERSION = '2.1';

=head1 VERSION

Version 2.1

=cut

use LWP::UserAgent;
use XML::Simple;

# if you're browsing this, please note: you also need a library to allow LWP to use SSL.
# Crypt::SSLeay or OpenSSL, for example

=head1 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

=head1 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.

=head1 DEPENDENCIES

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

=head1 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.

=head2 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');

=head2 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 C<status> will either return C<OK> or C<NOT OK>. If a request 
was able to be processed successfully; it will have a C<status> set to C<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 C<status> is C<NOT OK> there will be a 
detailed reason in the C<errstr> function, which otherwise will be C<undef>.

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

=cut

sub new {
    my $class = shift;
    my $self  = {};
    bless $self, $class;
    return $self;
}

sub status {
    my $self = shift;
    return $self->{status};
}

sub errstr {
    my $self = shift;
    return $self->{errstr};
}

=head2 Proxy

Function: C<proxy>

Parameters: C<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

=cut

sub proxy {
    my $self = shift;
    $self->{proxy} = shift;
    return;
}

=head2 Set Timeout

Function: C<set_timeout>

Parameters: C<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.

=cut

sub set_timeout {
    my $self = shift;
    $self->{timeout} = shift;
    return;
}

=head2 Ping

Function: C<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'
        };

=cut

sub ping {
    my $self = shift;
    my $st = $self->_get_url( { function => 'ping' } );
    return $st;
}

sub credentials {
    my $self     = shift;
    my $email    = shift;
    my $password = shift;
    $self->{email}    = $email;
    $self->{password} = $password;
    return;
}

=head2 Availability Check

Function: C<availability_check>

Parameters (all compulsory): C<DOMAIN-NAME.TK>, C<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'
        };

=cut

sub availability_check {
    my $self   = shift;
    my $domain = shift;
    my $length = shift;

    my $st = $self->_get_url(
        {
            function             => 'availability_check',
            domainname           => $domain,
            lengthofregistration => $length
        }
    );

    return $st;
}