Perl API Kit and Integration Guide

Follow the instructions below to begin integration with the API using Perl:

Make sure you have read the General API Integration Instructions first. If you have already integrated the PERL API Kit at your end, read the Change Log first to know what has changed since.

Step 1. Download the API Kit

Note

The SOAP API Kits have been deprecated. We recommend using the HTTP API instead. 1

Step 2. Download the API Documentation

The complete documentation of all classes and methods available in the API can be found in the Docs below. The Docs below are javadocs, but the function names and explanations remain the same for all the platforms and the documentation is self explanatory. We recommend you download the docs and read through them completely once before you integrate your application (updated on 6th September, 2009).

Core_Docs_v3_16.zip
Domains_Docs_v3_16.zip
Hosting_Docs_v3_16.zip
OtherProducts_Docs_v3_16.zip

Instructions to pass parameters to functions using the Perl Kit

Since Perl uses typeless variables you will have to ignore the datatypes presented in the docs. But for assigning values to variable of types other than strings and integers special care will have to be taken. Below is the list of datatypes presented in the API Doc and their usage in Perl.

Java Data Types Assigning values in Perl
String "firstname\@secondname.com"
int 123
HashMap (Datatype for storing name-value pair) {"domain1.com"=>1,"domain2.com"=>1}
Array and Vector (Datatype for storing more than one value) ["ns1.domain.com","ns2.domain.com"]
boolean (Datatype for storing true or false) TRUE / FALSE

Example:

  • For Calling a Function which takes a String datatype and an integer datatype as its paramters

    public int function1(java.lang.String userName, int parentid)
    $result = $obj->function1("firstname\@secondname.com",1);

  • For Calling a Function which takes a HashMap, a String Array and an integer Array as its parameters, where domainHash contains the domainname and the number of years as name value pairs.

    public java.util.HashMap function2(java.util.HashMap domainHash, java.lang.String[] orderby, int[] resellerId)
    $result = $obj->function2({"domain1.com"=>1,"domain2.com"=>2},["column1","column2"],[22,33])
  • For Calling a Function which takes a Vector and a boolean as its parameters

    public java.lang.String function3(java.util.Vector nameServers, boolean add)
    $result = $obj->function3(["ns1.domain.com","ns2.domain.com"],TRUE)

Step 3. Extract the files from the API Kit archive

You should get the following directory & files structure:

cgi-bin/ - Pre-written examples. You can directly run these examples to test API functionality
lib/ - The Perl classfiles, library files and wsdl files that you need to run your application

Step 4. Run the examples

You can run the pre-written examples provided in the examples folder. Note the following steps to do so:

  1. Upload the examples and lib folders to your web server where you run your Perl scripts. Make sure that both these folders are uploaded to the same parent folder.

  2. You must have a recent version of Perl (not newer than SOAP-Lite 0.60) installed on the server.

  3. You must have a Demo account ready the first time. Read the General instructions if you have not yet setup your demo account.

    Additional Information

    General API Integration Instructions

    Note

    The Demo server duplicates all functionality of the live server, however all Domain Names will appear as available on the Demo Server. It does not query the live registry and therefore names which are not available on the live registry will still appear as available on the Demo Server. At times connectivity to the DEMO Registry may be down resulting in errors.

  4. Make the appropriate changes to the constants.cgi file in the cgi-bin folder, by putting in the values for your username, password and parentid. The remaining settings have already been made for you in this file. You may only need to change the path for the wsdl folder if you have uploaded the wsdl folder elsewhere.

  5. The URL to which the call is made is maintained in the config.sh file inside the lib folder. You can make changes to this file and redirect your calls to the appropriate server.

  6. Import and point to note is that you will have to execute the config.sh file from the cgi-bin directory after making any changes in this file to reflect the changes.

  7. Every Example file has a set of functions which you can run.

  8. Once you have modified the appropriate example file, access it over your webserver by putting in your URL such as http://yourserver/examples/html and choose the required function from the links given in the left frame.

Note

In registering/managing any domain name on the demo server always use ns1.onlyfordemo.net and ns2.onlyfordemo.net as your nameservers. ANY OTHER Nameserver will result in an INVALID NAMESERVER error.

Step 5. Understanding Errors

Make sure you have read the General API Integration Instructions to obtain links to the error format and possible error documents.

Additional Information

General API Integration Instructions

Step 6. Writing your own code

After running each example above, if you simply refer to the corresponding .Perl file in the lib folder you will easily be able to figure out the code snippet you need to write in order to make a similar call.

Making an API call to perform any action is a matter of three steps:

  1. Include the appropriate Perl package as below -

    use lib::Customer;
  2. Obtain a pointer to the required Class. This is done by using the code below -

    our $Customer = new Customer($debugMode);
  3. Call the required method on this object. A complete reference of all methods is available in the Docs folder. This can be achieved by using the code below -

    $Customer->wsdlURL($wsdlFile);
    $Customer->StartServices()
    my @param = ($SERVICE_USERNAME, $SERVICE_PASSWORD, $SERVICE_ROLE, $SERVICE_LANGPREF, $SERVICE_PARENTID, $customerUserName, $customerPassword, $name, $company, $address1, $address2, $address3, $city, $state, $country, $zip, $telNoCc, $telNo, $altTelNoCc, $altTelNo, $faxNoCc, $faxNo, $customerLangPref);
Note

You will notice above that EVERY method in the docs takes the same first 5 parameters as -

String SERVICE_USERNAME, String SERVICE_PASSWORD, String SERVICE_ROLE, String SERVICE_LANGPREF, int SERVICE_PARENTID

In the examples these parameters have been put into a single constants file from which they are accessed by including the constants file. These parameters are common no matter which method you call. These parameters mean the following:

String SERVICE_USERNAME : Your Username
String SERVICE_PASSWORD: Your Password
String SERVICE_ROLE: This will always be a string reseller
String SERVICE_LANGPREF: The 2 letter code of the language in which you wish to receive errors and descriptions - en for English
int SERVICE_PARENTID: The ID of your parent which you can get from your profile section

Step 7. Change the information to Live information when you are ready

Once you have followed the steps above and got the test examples to work successfully, you can duplicate the same code in your live application and replace the Demo Server and Reseller account information with your live username and password. You will make this change in the config.sh file in the lib folder.