Peter Pentchev


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


  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' => '',
      'IP' => '');
  if ($@) {
    warn("Joker request failed: $@\n");


The WWW::Domain::Registry::Joker module provides a Perl interface to the Domain Management API (DMAPI) used by the DNS registrar. It is designed to help 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 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.


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

  • new ( PARAMS )

    Create a new interface object with the specified parameters:

    • username

      The reseller authentication username.

    • password

      The reseller authentication password.

    • debug

      The diagnostic output level, 0 for no diagnostic messages.

    • dmapi_url

      The URL to use for Domain Management API (DMAPI) requests; if not specified, the standard URL is used.

  • lwp ( [OBJECT] )

    Get or set the LWP::UserAgent object used for sending the actual requests to the 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 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 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.


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

  $jreq = new WWW::Domain::Registry::Joker('username' => '',
        '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/}).

Register a new nameserver:

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

Maybe some more examples are needed here :)


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

SEE ALSO - the DMAPI documentation


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

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

  • Better error handling; exceptions? Something completely different? Croak?

  • Croak instead of die here and there.


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


Peter Pentchev, <>


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.