.NET API Kit and Integration Guide

Follow the instructions below to begin integration with the API using .NET:

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

There are two ways by which you may install the API Kit on your computer:

Option 1 - Setup Application

We recommend that you download, unzip and run the setup file. First, however, please be sure that you have administrator privileges to install applications on the computer. If you're hosting your website with a third-party provider and do not have the rights to install applications, then you will not be able to use the setup application to install the kit. Therefore, you may manually install and use the required API files from our compressed ZIP file option (Refer to Option 2 below).

The setup application will perform the following tasks:

  1. A .NET dll containing the kit, and the relevant documentation, will be placed inside your Program Files folder; by default, the path would be C:\Program Files\. Therefore, you should be able to find the DLL and the documentation corresponding to your kit. Please ensure that you have the .NET runtime installed before you attempt to use the API kit.

  2. Relevant shortcuts will be placed in your start menu.

  3. If you have Microsoft Internet Information Server (IIS) version 5.0 or greater installed, the setup file will create a virtual directory named as OrderBoxCoreExamples, OrderBoxDomainsExamples, OrderBoxHostingExamples, OrderBoxOtherProductsExamples in your Default Web Site. The setup file allows you to give the virtual directory any name of your choice. This virtual directory contains a Visual Studio .NET project called OrderBoxCoreExamples , OrderBoxDomainsExamples, OrderBoxHostingExamples, OrderBoxOtherProductsExamples, which illustrates every function provided in the OrderBox API. You may run the examples by either by:

    • Opening it in Visual Studio.Net and pressing the F5 key, or

    • Visiting the url http://localhost/examples/ in your browser.

Option 2 - Compressed ZIP File

Download the zip file and extract the files to any temporary folder. The temporary folder will now contain the following subfolders:

  1. OrderBoxCoreExamples , OrderBoxDomainsExamples, OrderBoxHostingExamples, OrderBoxOtherProductsExamples - The folder contains the example files to illustrate every method in the kit.

  2. bin - This folder contains the actual kit DLL file. This is a .NET DLL, and requires the .NET runtime to be pre-installed, for use.

Installing the examples on your own computer:

  1. Create the Examples folder (OrderBoxCoreExamples , OrderBoxDomainsExamples, OrderBoxHostingExamples, OrderBoxOtherProductsExamples) inside the root of any website configured in IIS, on your computer. IIS contains a default website called Default Web Site, having it's root folder set to c:\Inetpub\wwwroot. If you have a default installation of IIS, you would create a subfolder called examples inside that root folder. Please note that you may name the examples directory as you please, you are not restricted to the name OrderBoxCoreExamples , OrderBoxDomainsExamples, OrderBoxHostingExamples, OrderBoxOtherProductsExamples.

  2. Open the IIS management console by navigating to Start > Programs > Administrative Tools > Internet Information Services.

  3. Now, we need to create an Application Root for the examples folder. This can be accomplished by opening the properties window for that directory and clicking the Create button.

If you successfully completed the above steps, you may open your browser and point it to http://localhost/examples (if you gave your examples folder some other name, replace the last word of the URL with that name).

Step 4. Run the examples

Please note first that the ASP.NET examples are provided solely to help illustrate usage of the ASP.NET Kit. You may use the example files directly, or simply use them as a reference project while developing your application to interface with the API.

Note

IIS 5.0 and the .NET runtime MUST be installed on your machine, BEFORE you run the kit setup file.

After you've installed the ASP.NET examples, open your browser, and point it to http://localhost/your-examples-folder (you may use the name given to the examples folder to replace examples in the preceding url). This shall open the ASP.NET examples webpage, which is divided into three frames:

  • The frame on the top allows you to mention the Service URL, your Reseller Username, your Password, ParentID, Language Preference, Role, Debug Mode to make API calls independent of the credentials provided in the APIConstants.vb file. This frame also provides you a checkbox to enable/disable the credentials of this frame. That is, if the checkbox is not selected the APIConstants.vb file credentials will be used to make the API call.

  • The lower left frame contains a list of links to pages that illustrate the use of each method in the API. When you click a link, it's corresponding page is displayed in the right hand side frame. You may test the functions by putting in the call parameters in the page.

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

The API classes exist within the namespace OrderBoxCoreLib , OrderBoxDomainsLib, OrderBoxHostingLib, OrderBoxOtherProductsLib. The class named "Properties", contains static variables useful for debugging, and changing the SOAP End Point.

The following are valid end points for the OrderBox Demo Server for API Kits ver 3.x and above:

Note

Following are valid end points for the OrderBox Demo Server for older API Kits:

The following are valid end points for the OrderBox Live Server:

Note

Following are valid end points for the OrderBox Live Server for older API Kits:

Example:

To test the examples, you must first create an account on the Demo server. To use the Customer webservices of the API, instantiate the customer object as demonstrated below. If at any time the SOAP end point must be changed to some other url, you may simply put the new SOAP end point into this variable.

Properties.Url = "http://soap-end-point";

The following code instantiates the Customer object. You may now use it's methods to call various OrderBox API functions. These are SOAP calls, that will be made to the SOAP End Point specified by the Propeties.Url variable.

Customer oCustomer = new Customer ();

To illustrate the use of this object, we shall take the example of a method called getCustomerId. Examine the code snippet below. It uses an object of the Customer class to request the id of a specified username.

int result = 0; 

// First we make sure that our SOAP End Point is pointing to the correct resource.
Properties.Url = "http://api.onlyfordemo.net/anacreon/servlet/APIv3-XML";

// The examples use a class called Constants, containing static properties that hold your credentials. You may set these properties once, and later in the file simply pass them to the method calls as required. The values set below are simply examples, and must be replaced with your own credentials.
Constants.Username = username@domain.com;// Your username goes here.
Constants.Password = your-password;// Your password goes here.
Constants.Role = reseller;// Your role goes here.
Constants.LangPref = en;// Your language preference goes here.
Constants.ParentID = 1;// Your parent id goes here.

// Since we wish to view the soap request and response ...
Properties.Debug = true;

// Next we instantiate an object of the Customer class.
Customer oCustomer = new Customer ();

// We then use this customer object to request the id for a specified username.
result = oCustomer.getCustomerId (ApiConstants.SERVICE_USERNAME,
ApiConstants.SERVICE_PASSWORD,
ApiConstants.SERVICE_ROLE,
ApiConstants.SERVICE_LANGPREF,
ApiConstants.SERVICE_PARENTID,
"username");

// Now we display the soap request.
Console.WriteLine (Properties.getLastRequest); Console.WriteLine ();

// Then we display the soap response.
Console.WriteLine (Properties.getLastResponse); Console.WriteLine ();

// Lastly we display the result.
Console.WriteLine (result);

The above code accepts authentication details and a username, and returns an integer value, which is the id corresponding to the username passed. The last parameter of the getCustomerId method is the username for which we requested an id. This id was returned into the integer variable result.

Please note the first five parameters of this method call. They consist of the username, password, role, language preference, and parent id respectively, of the individual calling the method. For the examples, you may make a demo account on the demo server, and pass the username, password, role, language preference and parent id from your demo account to this method call. These are the first five parameters that are passed to every API call that is undertaken. Please make sure that you pass accurate details for these parameters. If you do not, your method call will be unsuccessful.

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 7. Change the information to Live information when you are ready

When you have got the examples working correctly, you may set the value of Properties.Url to one of the live URL's, and pass your own authentication details when making API calls.