view release on metacpan or  search on metacpan

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

package Domain::Register::DomainShare;

our $VERSION = '1.02';

=head1 NAME
Domain::Register::DomainShare - an interface to Dot TK's DomainShare API

=cut

=head1 SYNOPSIS

  # use the library
  use Domain::Register::DomainShare;

  # create a new client for DomainShare
  my $client = Domain::Register::DomainShare->new();

  # ping DomainShare server
  my $result = $client->ping();

  ...

  # check domain availability  
  my $result = $client->availability_check({
      email => 'domainshare@example.tk',
      password => 'password',
      domainname => 'testdomain1.tk'
  });

=cut

=head1 DESCRIPTION

Dot TK's DomainShare API service lets developers design computer programs and 
online applications that interact directly with the Dot TK registration system 
for FREE domain name registration services.

That basically means that Dot TK allows developers to register free domain names 
with the .TK extension from their applications.

For more information and a list of available functions, please review the technical
documentation available via http://domainshare.tk.


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

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.

A full list of available functions is available via the technical documentation 
available via http://domainshare.tk.


=head1 MULTIVALUE PARAMETERS

Although most calls require unique values for the given parameters, some of them
should or could be multivalue. An example multivalue parameter is nameserver.
When registering a domain with specifying nameservers, you need to pass at least
two nameservers.

  # register domain
  my $result = $client->register({
      email => 'domainshare@example.tk',
      password => 'password',
      domainname => 'testdomain1.tk',
      nameserver => ['ns1.example.tk', 'ns2.example.tk' ]
  });

As you see, the multivalue parameter can simply be specified by an array reference.


=head1 RETURN VALUES

Any call to a function will return an array where first element is status code.
The status code will be set to 1 upon success, 0 upon failure. The second element
is a hashref with either an error discription data, or the function's return result. 

Success looks like this:

  $VAR1 = [
	    1,
	    {
	      'status' => 'DOMAIN AVAILABLE',
	      'type' => 'result',
	      'domainname' => 'TEST123.TK',
	      'domaintype' => 'FREE'
	    }
	  ];

Error looks like this:

  $VAR1 = [
	    0,
	    {
	      'reason' => 'Invalid domain name',
	      'type' => 'Server Error'
	    }
	  ];

"type" can be 'Server Error' or 'Input Error'. 'Server Error' means the error was 
returned by API server Input Error relates to missed mandatory fields. Error message
is in the "reason" field in both cases.

=cut

use strict;
use warnings;