Using Web Services

Greg Kolinski edited this page Sep 28, 2017 · 6 revisions

Back To ECGridOS User's Guide Home


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 most current web services are located at

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. You will need an API Key to access all methods except for NowUTC() and Version(), 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, you use Website/Add Web Reference... to create a reference to ECGridOS using the above URL.

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


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

web.config

<configuration>
    <appSettings>
        <add key="net.ecgridos.ECGridOSAPIv3" value="http://ecgridos.net/v3.2/ecgridos.asmx" />
    </appSettings>
</configuration>

app.config

<configuration>
    <applicationSettings>
        <ECGrid_API.Properties.Settings>
            <setting name="ECGrid_API_net_ecgridos_ECGridOS_x0020_API_x0020_v3" serializeAs="String">
                <value>https://ecgridos.net/v3.2/prod/ecgridos.asmx</value>
            </setting>
        </ECGrid_API.Properties.Settings>
    </applicationSettings>
</configuration>

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

C#

net.ecgridos.ECGridOSAPIv3 ecgridos = new net.ecgridos.ECGridOSAPIv3();

or

using ECGridService = <ProjectName>.net.ecgridos;
ECGridService.ECGridOSAPIv3 ecgridos = new ECGridService.ECGridOSAPIv3();

Visual Basic

Private ecgridos As New net.ecgridos.ECGridOSAPIv3

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

C#

using ECGridService = <ProjectName>.net.ecgridos;
ECGridService.ParcelIDInfo Parcel = new ECGridService.ParcelIDInfo();

Visual Basic

Dim parcel() As net.ecgridos.ParcelIDInfo

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

C#

using ECGridService = <ProjectName>.net.ecgridos;
ECGridService.ECGridOSAPIv3 ECGrid = new ECGridService.ECGridOSAPIv3();
ECGridService.ParcelIDInfo Parcel = new ECGridService.ParcelIDInfo();
Parcel = ECGrid.ParcelInBoxArchiveEx(SessionID, NetworkID, MailboxID, BeginDate, EndDate, EDGridIDFrom, ECGridIDTo, MailbagControlID, PageNo, RecordsPerPage);

of if you prefer

using ECGridService = <ProjectName>.net.ecgridos;
ECGridService.ECGridOSAPIv3 ECGrid = new ECGridService.ECGridOSAPIv3();
var ParcelInfo = ECGrid.ParcelInfo(SessionID, ParcelID);

Visual Basic

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

  • get web service client - authenticate with API/Session Key
  • method()
  • close web service client

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.


Back To ECGridOS User's Guide Home

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.