Using Web Services


ECGridOS is a Web Services API built on the Microsoft .NET Framework. It can be accessed through any system capable of making Web Services calls.

What is a Web Service?

In a nutshell, Web Services are simply remote class library. It contains properties and methods just like any other class. There are also a set of classes to define various return Objects and ENUMs to assist in building function calls. It really is very simple.

Attaching to the ECGridOS Web Services

The ECGridOS v2 web services are located at:

Production:

https://ecgridos.net/v2.3/prod/ECGridOS.asmx

Given the confidential nature of electronic commerce, ECGridOS can only be accessed securely over HTTPS.

While ECGridOS can be accessed through HTTP GET and POST methods, it is highly recommended that you use the SOAP v1.1 or v1.2 protocol as GET and POST may be removed at a future date.

If you open the above URL in a web browser, you will see the list of all the methods defined to ECGridOS v2.1. Each link describes in detail how requests and responses are formatted, along with the ability to make test calls right from the browser. You will need a LoginName and Password to access all methods except for NowUTC(), which can be used as a quick test.

Have no fear, a development tool that recognizes a WDSL file will automatically import everything you need directly into your development environment. Using Visual Studio 2008, you use Website/Add Web Reference... to create a reference to ECGridOS using the above URL.

The default name will be net.ecgridos.ECGridOSAPIv2. This can be given a shorter name if you desire.

In the Microsoft development environment, you will see the following entry in the web.config file:

web.config

<configuration>
  <appSettings>
      <
add key="net.ecgridos.ECGridOSAPIv2" value="http://ecgridos.net/v2.3/ecgridos.asmx" />
  </
appSettings>
</configuration>

In order to access the ECGridOS web services, it must first be instantiated by declaring it as a new object.

Visual Basic

Private ecgridos As New net.ecgridos.ECGridOSAPIv2

All Object and Object Collection declarations require a similar reference to its respective web service class:

Visual Basic

Dim parcel() As net.ecgridos.ParcelIDInfo

When calling an ECGridOS API, reference the method of your object:

Visual Basic

Dim SessionID As String = ecgridos.Login(LoginName, Password)

Dim parcels() As net.ecgridos.ParcelIDInfo = _
                 ecgridos.ParcelInBoxArchiveEx(SessionID, _
                                              
NetworkID, _
                                               MailboxID, _
                                               BeginDate, _
                                               EndDate, _
                                               ECGridIDFrom, _
                                               ECGridIDTo, _
                                               Status)

Programming Philosophy

The basic philosophy of using ECGridOS is by discrete session. Which at the highest level consists of the following steps

  1. login()
  2. method-1() 
  3. method-2() 
  4. ...
  5. method-n() 
  6. logout()

A typical, complete session only last a few seconds. Sessions cannot be established and held open, but shall be opened and closed as needed.

Data returned from the APIs can be single values, datasets, objects or collections of objects (returned as arrays).

When returning datasets and collections of objects, keep in mind that the entire response is returned at once, as no cursors are created as with a SQL server. Discretion should be used to not create a request that generates excessively large responses as this will significantly affect performance and local memory requirements.

See Also

ENUMs
Object Classes
Sessions
SOAP Exceptions


© 2008-2011, Loren Data Corp.
All rights reserved.
ECGrid is a registered service mark of Loren Data Corp.
ECGridOS is a service mark of Loren Data Corp.