|
.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.
Reference:
General API
Integration Instructions >>
Change Log >>
Step 1. Download the API Kit
Click the link below to download the relevant API kits (updated on 6th
March, 2008).
Option 1 - Setup Application
NET_Core_Setup_v3_10.zip
NET_Domains_Setup_v3_10.zip
NET_OtherProducts_Setup_v3_10.zip
Option 2 - Compressed ZIP File
NET_CoreExamples_v3_10.zip
NET_DomainsExamples_v3_10.zip
NET_OtherProductsExamples_v3_10.zip
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 March,
2008).
Core_Docs_v3_10.zip
Domains_Docs_v3_10.zip (updated on
4th June, 2008)
OtherProducts_Docs_v3_10.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:
-
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.
-
Relevant shortcuts will be placed in your
start menu.
-
If you have Microsoft Internet Information
Server version 5.0 or greater (IIS) installed, the setup file will create a
virtual directory named as OrderBoxCoreExamples , OrderBoxDomainsExamples, 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, 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:
-
OrderBoxCoreExamples , OrderBoxDomainsExamples, OrderBoxOtherProductsExamples - The folder contains the example
files to illustrate every method in the kit.
-
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:
-
Create the Examples folder (OrderBoxCoreExamples , OrderBoxDomainsExamples, 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, OrderBoxOtherProductsExamples.
-
Open the IIS management console by navigating
to "Start > Programs > Administrative Tools > Internet Information Services"
-
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 on 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 OrderBox API.
IMPORTANT
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.
Reference:
General API Integration Instructions >>
Step 6. Writing your own code
The API classes exist within the namespace
OrderBoxCoreLib , OrderBoxDomainsLib, 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:
The following are valid end points for the
OrderBox Live Server:
Example: To test the examples, you must first
create an account on the Demo server. To use the Customer webservices of the
OrderBox 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.
IMPORTANT
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.
|
