NAME

WWW::Domain::Registry::Joker - an interface to the Joker.com DMAPI

SYNOPSIS

  use WWW::Domain::Registry::Joker;

  $reg = new WWW::Domain::Registry::Joker('username' => 'testuser',
    'password' => 'secret', 'debug' => 1);

  @res = $reg->result_list();

  eval {
    $procid = $reg->do_request('ns-create', 'Host' => 'a.ns.example.com',
      'IP' => '192.168.13.1');
  };
  if ($@) {
    warn("Joker request failed: $@\n");
  }

DESCRIPTION

The WWW::Domain::Registry::Joker module provides a Perl interface to the Domain Management API (DMAPI) used by the Joker.com DNS registrar. It is designed to help Joker.com resellers in automating the domain registration and all the other relevant actions.

The recommended usage of the WWW::Domain::Registry::Joker class is to create an object, initialize it with the Joker.com reseller's username and password, and then use it to send all the DMAPI requests. This will take care of caching both login credentials and network connections (at least as far as LWP takes care of caching connections to the same webserver).

In most cases it is not necessary to invoke the login() method explicitly, since all the "real" action methods check for an authentication token and invoke login() if there is none yet.

METHODS

The WWW::Domain::Registry::Joker class defines the following methods:

• new ( PARAMS )

  Create a new Joker.com interface object with the specified parameters:

  • username

    The Joker.com reseller authentication username.

  • password

    The Joker.com reseller authentication password.

  • debug

    The diagnostic output level, 0 for no diagnostic messages.

  • dmapi_url

    The URL to use for Joker.com Domain Management API (DMAPI) requests; if not specified, the standard URL https://dmapi.joker.com/request is used.

• lwp ( [OBJECT] )

  Get or set the LWP::UserAgent object used for sending the actual requests to the Joker.com web API.

  This method should probably never interest any consumers of this class :)

• build_request ( REQUEST, PARAMS )

  Build a HTTP::Request object for submitting an actual request to the Joker.com API.

  This method should probably never interest any consumers of this class :)

• login ()

  Send a DMAPI login authentication request and obtain the auth SID for use in the follow-up actual requests. The username and password member variables must be initialized.

• query_domain_list ( PATTERN )

  Return information about the domains registered by this reseller whose names match the supplied pattern. Returns a hash indexed by domain name, each element of which is a hash:

  • domain

    The domain name (yes, again :))

  • exp

    The expiration date of the domain registration.

  Invokes the login() method if necessary.

• do_request ( REQUEST, PARAMS )

  Send a DMAPI request with the name specified in REQUEST and parameters in the PARAMS hash. The request name string and the parameters (required and optional) are as specified by the DMAPI documentation

  Note that for object modification requests (those which type is domain-owner-change or ends in -modify) if a parameter is supplied with the empty string as a value, the do_request() method will send the "!@!" string instead, since the DMAPI considers empty values to mean no change requested.

  Invokes the login() method if necessary.

• result_list ()

  Obtain the list of processed requests from the Joker.com DMAPI and the corresponding result status and object ID (where applicable). Returns a hash indexed by DMAPI Proc-Id values.

  Invokes the login() method if necessary.

EXAMPLES

Initialize a WWW::Domain::Registry::Joker object with your reseller's username and password:

  $jreq = new WWW::Domain::Registry::Joker('username' => 'me@example.com',
        'password' => 'somekindofsecret');

Fetch the list of pending and processed requests and their status:

  %h = $jreq->result_list();
  foreach (sort { $a->{'procid'} cmp $b->{'procid'} } values %h) {
        print join("\t",
            @{$_}{qw/tstamp svtrid procid reqtype reqobject status cltrid/}).
            "\n";
  }

Register a new nameserver:

  eval {
        $jreq->do_request('ns-create', 'Host' => 'a.ns.example.net',
            'IP' => '192.168.13.7');
  };
  print STDERR "ns-create error: $@\n" if ($@);

Maybe some more examples are needed here :)

ERRORS

All the user-invoked methods die on any Joker.com errors with a suitable error message placed in $@.

SEE ALSO

https://joker.com/faq/category/39/22-dmapi.html - the Joker.com DMAPI documentation

BUGS

• Reorder the methods placing the user-serviceable ones first.

• Move WWW::Domain::Registry::Loggish to a separate distribution?

• Better error handling; exceptions? Error.pm? Something completely different? Croak?

• Croak instead of die here and there.

HISTORY

The WWW::Domain::Registry::Joker class was written by Peter Pentchev in 2007.

AUTHOR

Peter Pentchev, <roam@ringlet.net>

COPYRIGHT AND LICENSE

Copyright (C) 2007 - 2009 by Peter Pentchev

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm WWW::Domain::Registry::Joker

perl -MCPAN -e shell
install WWW::Domain::Registry::Joker