Advantage Web API with Windows Mobile

The Advantage Web API is a framework for allowing developers to access their data from virtually anywhere on just about any device. It consists of a set of pre-built web services running on a lightweight version of Apache. The interface will provide both SQL and Table style access methods to Advantage data. Communication is secure over HTTPS using SSL and requires data dictionary authentication. The basic architecture is shown below.

Now that we have established the basic framework it is time to create a simple Windows Mobile 6 application that retrieves data from the Advantage Web API. In this case we are going to simply send a query to the server to retrieve a list of customers as shown.

The first step is to create our web request with an appropriate URL. We then need to add some header information which includes the result type ( application/JSON ) and our authentication. Once the request has been created we then execute the request. The request is sent via HTTPS ensuring that the authentication and data are transferred securely. This means that the server is using some type of certificate to provide the secure communication.

string sURI = "https://localhost:6282/adsweb/example/v1/query/";
sURI += "SELECT%20*%20FROM%20CustomerList";
HttpWebRequest request = WebRequest.Create(sURI) as HttpWebRequest;
request.Accept = "application/json";
string auth = "Basic " + Convert.ToBase64String(Encoding.ASCII.GetBytes("adssys:"));
request.Headers["Authorization"] = auth;

In my case I am using a self-signed certificate which is not recognized by the device. Initially when I made the request i received a "Could not establish a trust relationship with remote server" error message. This is because there is no default mechanism for allowing users to accept an unknown certificate. In order to resolve this error by creating a custom certificate verification handler. You can get all the details from this MSDN article.

The next step is to process the result returned by the request. The data is returned back as a JSON string that we can parse. In my case I used the JSON.NET library from CodePlex to create my own parser. The AdsDataObject stores metadata contained in the request and dynamically builds a DataTable based on the returned data. I'll provide the details on this object in a future post.

Here is the code that processes the response to the web request. Once the request has been processed the data can be shown in the data grid.

using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
  using (Stream dataStream = response.GetResponseStream())
  {
    using (StreamReader reader = new StreamReader(dataStream))
    {
       string json = reader.ReadToEnd();

       oData = new AdsDataObject(json);
       dgCustomer.DataSource = oData.dataTable;
    }
  }
}

By default a maximum of 20 rows are returned with each request, you can change this by using the $top parameter ( i.e. …/query/select%20*%20from%20table?$top=10). The request includes an additional parameter, named __next, which contains a URL for getting the next records. The parser/deserializer that you use will need to capture this value.