Java API Kit and Integration Guide

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

Make sure you have read the General API Integration Instructions first. If you have already integrated the Java 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

Step 3. Extract the files from the API Kit archive

You should get the following directory & files structure:

WEB-INF/classes/ - Precompiled examples. You can directly run the examples to test API functionality
examples/src/ - The examples for using the API
WEB-INF/lib/ - The jar files that you will need in order to compile/run the classes
WEB-INF/build.xml - The API archive also contains a build.xml file. You can use this file to build the examples using Ant.

The Ant target to build the examples is build. If you do not want to use Ant, you can just compile the files in the src folder. You will need to include the jar files provided in the lib folder while compiling the classes.

Step 4. Run the examples

You can run the precompiled examples provided in the classes folder. Note the following however:

  1. Upload the classes and lib folders to your server. Make sure that both these folders are uploaded to the same parent folder.

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

  3. Make the appropriate changes to the settings.properties file in the WEB-INF\classes\com\logicboxes\properties folder, by putting in the values for your ResellerUsername, ResellerPassword and ParentId. The remaining settings have already been made for you in this file.

  4. The URL to which the call is made is maintained in the settings.properties file inside the WEB-INF\classes\com\logicboxes\properties folder. By default, all calls are made to the demo server URL using HTTP. You can make changes to this file and redirect your calls to the appropriate server.

    Note

    If you are using HTTPS calls you MUST have JDK 1.4 or greater installed. HTTPS calls will not work with JDK 1.3 or lower.

  5. Set your class path to include the bin folder and EVERY jar file in the lib folder. You would use the following command for that -

    Windows

          set CLASSPATH=%CLASSPATH%;
          </fullPathTo>/classes;
          </fullPathToLibFolder>/aaxerces-1_4_3.jar;
          </fullPathToLibFolder>/axis.jar;

          </fullPathToLibFolder>/commons-discovery.jar;
          </fullPathToLibFolder>/commons-logging.jar;
          </fullPathToLibFolder>/jaxrpc.jar;
          </fullPathToLibFolder>/junit.jar;
          </fullPathToLibFolder>/logicboxes-sfnb-v2.jar;
          </fullPathToLibFolder>/saaj.jar;

          </fullPathToLibFolder>/servlet.jar;
          </fullPathToLibFolder>/wsdl4j.jar
       

    Linux

          set CLASSPATH=$CLASSPATH:
          </fullPathTo>/classes:
          </fullPathToLibFolder>/aaxerces-1_4_3.jar:

          </fullPathToLibFolder>/axis.jar:
          </fullPathToLibFolder>/commons-discovery.jar:
          </fullPathToLibFolder>/commons-logging.jar:
          </fullPathToLibFolder>/jaxrpc.jar:
          </fullPathToLibFolder>/junit.jar:
          </fullPathToLibFolder>/logicboxes-sfnb-v2.jar:

          </fullPathToLibFolder>/saaj.jar:
          </fullPathToLibFolder>/servlet.jar:
          </fullPathToLibFolder>/wsdl4j.jar
       
  6. Run the java program using the command line below

       java -classpath $CLASSPATH com.logicboxes.foundation.sfnb.user.CustomerServiceLocator <params for test class>

    To find out the parameters that the command above takes you can simply choose to not pass any parameter the first time you run it. The example will print out the parameters that it expects.

    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.

    Follow the same instructions above to run all the examples as below:

    • Domain Contact example:

            java -classpath $CLASSPATH com.logicboxes.foundation.sfnb.order.DomainContactServiceLocator <params required for the class>
         
    • Domain example:

            java -classpath $CLASSPATH com.logicboxes.foundation.sfnb.order.DomainServiceLocator <params required for the class>
         
    • Fund example:

            java -classpath $CLASSPATH com.logicboxes.foundation.sfnb.management.FundServiceLocator <params required for the class>
         

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 .java file in the src 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 two steps:

  1. Obtain a pointer to the required service. This is done by using the code below -

          com.logicboxes.foundation.sfnb.user.Customer customerObj = new com.logicboxes.foundation.sfnb.user.CustomerServiceLocator(serviceAddress).getCustomerService();
       

    In the above call serviceAddress is passed as a parameter to the constructor of CustomerServiceLocator. This serviceAddress refers to the URL of the server to which you are communicating. You can obtain this URL from the "settings.properties" file in the "WEB-INF\classes\com\logicboxes\properties" folder.

  2. Call the required method on this object. A complete reference of all methods is available in the Java Docs. This can be achieved by using the code below -

       int customerId = customerObj.addCustomer(resellerUserName, resellerPassword, "reseller",resellerLangPref, parentId, customerUsername, customerPassword, name, company,address1, address2, address3, city, state, country, zip,telNoCc, telNo, altTelNoCc, altTelNo, faxNoCc, faxNo, langPref);
Note

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

      java.lang.String userName, java.lang.String password, java.lang.String role, java.lang.String langpref, int parentid
   

These parameters are common no matter which method you call. These parameters mean the following -

java.lang.String userName: Your Username
java.lang.String password: Your Password
java.lang.String role: This will always be a string reseller
java.lang.String langpref: The 2 letter code of the language in which you wish to receive errors and descriptions - en for English
int 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. The URL that you make your calls to also needs to change to the LIVE Server URL. The list of URLs are available in the "settings.properties" file inside the "WEB-INF\classes\com\logicboxes\properties" folder.

Note

If you are using HTTPS calls you MUST have JDK 1.4 or greater installed. HTTPS calls will not work with JDK 1.3 or lower.