Retrieval and Parsing of XML Formatted API data.

• Sample Application - 64.8 KB

Introduction

For beginners working with API XML data, it can be a confusing time wondering how to receive and handle the information received. With hundreds of ways to get the information, it can add on to the confusion for the new developer.

Therefore, I created a simple application that can be understood and used universally. It is made to be extremely straightforward on its approach on how to get the information.

Understanding the Code

Picking a very basic API (in this case to get definitions), the application is able to get, parse, format, and output into user readable information. Let's find out how to do that. 

API Knowhow

When connecting to an API service, most times, the service will ask you to sign up and apply to get an API Key. That key will then, most times, be requested to be inputted into a query. A query can mean many different things when referring to programming.  Ultimately, a query is your bridge to get information from the API service to your application.

First, see if you can get an API key to the wanted API service (if required). Without the key the query will fail. The API key is your key to access the API service. There is no sense spending time developing an application, which is useless without that API key access. 

In this application, I have used STANDS4 Web Services: Dictionary Definitions API. Click "Apply here" at the bottom and follow the instructions to get the API key to use this application. While it is not necessary, it is highly recommended.  

The STANDS4 query is a Request URL. A Request URL is a type of query that gets the information from a webpage using Parameters.

Here is the Request URL:

http://www.stands4.com/services/v2/defs.php

If you click this you will get an error. The reason behind this is because this Request URL needs Parameters. 

The three Parameters are:

1. uid - Your API user ID.
2. tokenid - Your developer token ID.
3. word - The word that you want to get your definition for.

So a sample Request URL will look like:

http://www.stands4.com/services/v2/defs.php?uid=[youruidkey]&tokenid=[yourtokenidkey]&word=[wordtosearch]

This will be the query Request URL. The real meat of the program. 

Understanding XML DATA

We now have our Request URL for our query. So what do we do. We test it out on our web browser to see what kind of information it gives. This will be your Sample Responce. A Sample Responce can be in many different information formats (text, XMl, Json, Pictures, ect). This example uses a XML format.

A Sample Responce is like this:

<?xml version="1.0" encoding="UTF-8"?>

<results>

    <result>

        <term>consistent, uniform</term>

        <definition>the same throughout in structure or composition</definition>

        <partofspeech>adj</partofspeech>

        <example>bituminous coal is often treated as a consistent and homogeneous product</example>
    </result>

</results>

At the top you will see the information format, this very important to understand being that for different formats there will be different processing methods. 

XML data is in a Tree format. Everything is branched off to another thing. The beginning branch is "results", this is referred to as the root. Inside the root there can be many sub-roots. This example only has one sub-root which is named "result." Inside your sub-roots you will get responce elements. This is the information that you will use in your application.

The example responce elements are:

• term - String
• definition - String
• partofspeech - String
• example - String

Take note of these elements. You will need to remember their names later. 

Please note that while this XML tree is the design of this example, some times there can be sub-roots inside of sub-roots. Understanding the tree is the only way to build a program to get the correct information from the tree.

Using the code

Now that you understand what API's are, how important API keys are, and the basic XML data structure lets make a program. 

If you see fit, I will leave all the design and basic project creation up to you.

Getting a Query

To get a Query will will need to make a WebRequest. The WebRequest reference is in System.Net.

You will need to add that reference in the top of the application using the "using" command. 

using System.Net;

Also under the class we will need to make an application wide variable. While you can include variables into the voids, if you are reusing variables it's better to have them always in memory. Making them a application wide variable speeds up the responce time for Querys. 

Under the public partial class [yourformname] : Form bracket please enter: 

WebResponse webResponse;

Now we need to make a private void with a string attached to it (so we can get the search word).

private void Query(string word)
{
}

In the brackets of your new private void add in this code:

var webRequest = WebRequest.Create([Request URL]);

This will make a variable for the Query. We can do all sorts of things with this.

Let's now try to get the Query. The key word is try, if the Query is invaild we will not get anything we can work with. Thus is important that a try and catch command is there.

try
{
    webResponse = webRequest.GetResponse();
}
catch (WebException)
{
    textbox.Text = "No internet connection.";
    return;
}
catch (Exception e)
{
    textbox.Text = "Something went wrong." + e;
    return;
}

This will get a responce from the API service. If the user is not connected to internet it will invoke a WebException, making an error message saying "No internet connection." If something goes wrong, but is not about the internet, it will do an error message saying "Something went wrong" with the Exception. 

Next we will connect to the API service:

var appCastStream = webResponse.GetResponseStream();

This opens up a steam from the API service using the Request URL.

Now if the Request URL is invaild and returns nothing we might have a problem. Thus lets check if it is not null:

if (appCastStream != null)
{
    receivedAppCastDocument.Load(appCastStream);
}
else
{
    textbox.Text = "API is down. Please try again later";
    return;
}

If we got information from the Query it will load the information into our application.

ReceivedAppCastDocument is a System.XML reference.  Make sure to add that to your using list:

using System.Xml;

Great Job! We now have information from the Query!

Parsing

The only thing left to do is get the information from the Query. This retieval act is called parsing. ReceivedAppCastDocument makes it extreamly easy to do.

This is also where having a sample request open on your browser comes in handy. 

We will now remember the sample request XML tree's structure. This is to build an index to parse the information. It will tell the computer where exactly to find the information and what to do with it.

var result = receivedAppCastDocument.SelectNodes("results/result");

ReceivedAppCastDocument.SelectNodes makes an Xpath of the XML. This builds the index. "results/result" is the tree to get to the responce elements.  First with the root then to the sub-root. If you have different named root and sub-roots please change it accordingly. Please note that LETTER-casing needs to be exact from here on in.   

Let's now check if we have any responce elements:

if (result != null)
{
}

This checks if result is null. If it isn't then it carries on. What's cool about this, is that we can add a "else" statement and do something if we have no responce elements. 

This is now where it gets complicated. We will now select and get information from the responce elements, however if there is many sub-roots with responce elements we want to make sure that we do not overwrite them. Sounds complicated? But the solution is as simple as making a foreach command. 

foreach (XmlNode item in result)
{  
    var term = item.SelectSingleNode("term").InnerText;
    var partofspeech = item.SelectSingleNode("partofspeech").InnerText;
    var definition = item.SelectSingleNode("definition").InnerText;
    var example = item.SelectSingleNode("example").InnerText;
}

As you can see assigning a variable to the responce elements is not hard. This foreach command makes a new "item" that can be indexed to get the InnerText of the responce element. Being that it's a foreach command it does this for every single sub-root. 

Now you have the information from the Query in string variable to do as you please. I always recommend checking to see if the variables are valid/not empty. To do this on a string you need to make a if statement.

if (term != "")
{
}
else
{
}

This counteracts any blank spots in your formating. 

Conclusion

If you actually read all that, congratulations! I hope that you have learned a lot. 

Test out the sample source included. It hopefully it helps your understanding. 

Cheers!

If you liked it make sure that you give me a rate. 

Ps. Remember that not every Xml document is the same, some may be much more complex then this example. If you run into a problem with a API formating the best way to get answers is contacting support for that API service.