Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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 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:
<configuration> <appSettings> <add key="net.ecgridos.ECGridOSAPIv3" value="http://ecgridos.net/v3.2/ecgridos.asmx" /> </appSettings> </configuration>
<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.
net.ecgridos.ECGridOSAPIv3 ecgridos = new net.ecgridos.ECGridOSAPIv3();
using ECGridService = <ProjectName>.net.ecgridos; ECGridService.ECGridOSAPIv3 ecgridos = new ECGridService.ECGridOSAPIv3();
Private ecgridos As New net.ecgridos.ECGridOSAPIv3
All Object and Object Collection declarations require a similar reference to its respective web service class:
using ECGridService = <ProjectName>.net.ecgridos; ECGridService.ParcelIDInfo Parcel = new ECGridService.ParcelIDInfo();
Dim parcel() As net.ecgridos.ParcelIDInfo
When calling an ECGridOS API, reference the method of your object:
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);
Dim parcels() As net.ecgridos.ParcelIDInfo = ecgridos.ParcelInBoxArchiveEx(SessionID, NetworkID, MailboxID, BeginDate, EndDate, ECGridIDFrom, ECGridIDTo, Status)
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
- 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.