Editor’s note: This blog post is a basic tutorial. The most up-to-date version is available in the wiki.

Between RESTful and SOAP based web services, there’s an endless supply of data out there just waiting for you to pick it up. Wouldn’t it be great to query this data directly from your Appcelerator app? Of course it would, and fortunately Appcelerator has a simple and familiar interface for doing so.

Titanium.Network.HTTPClient, as its name implies, allows you to make client calls to HTTP web services. It is a specialized implementation of the XmlHttpRequest specification that works with your native Appcelerator code. Let’s take a look at how we can use this interface to query data from a remote source and use it in your app.

Titanium.Network.HTTPClient skeleton

So let’s breakdown what’s happening here in this snippet. After we create a variable to hold our target URL, we create the HTTPClient. When we do so, we set up 2 important event handlers:

• onload – This is the function that will be called upon successful response from the target URL. The response data can be processed using 3 different properties of the HTTPClient:
  • this.responseText – Contains the raw text response from the target URL. This is the property that would be used when processing JSON or other plain text data.
  • this.responseXML – Contains any XML formatted data from the response. As you might expect, this property is most appropriate for processing SOAP and other XML based web services.
  • this.responseData – Contains your response data in binary format.
• onerror – This is the function that will be called in the event of an error in your response. To help troubleshoot errors, there are again 3 properties you can check, though this time one belongs to the event object:
  • this.responseText – Like with onload, this contains any text data that was returned with your error response.
  • this.status – Contains the returned status code of the error.
  • e.error – Contains additional error information included in the event object e.

As you can see, these 2 event handlers are the heavy lifters when it comes to HTTPClient. They determine how the data will be handled once it is returned asynchronously from your HTTPClient call.

One final property we’ll set is timeout which will abort our asynchronous call after the specified number of milliseconds. This prevents a flaky web service from stealing control from your app’s flow for too long.

To actually send the prepared HTPPClient call, we simply open() our HTTPClient connection with a connection type (either GET or POST) and our target URL. Once the connection is opened, we then send our asynchronous request via send(). And that’s it. From here on out, all of the HTTPClient flow is handled by our previously defined event handlers.

Sample App: ‘Fighters’

So now that you understand the nuts and bolts of a basic HTTPClient request, let’s get to a full sample app. We’re going to retrieve a static JSON file that includes a list of fighters names and nicknames, then display that data in a Titanium.UI.TableView.

We will be working with remote JSON formatted data. JSON is far more lightweight and easier to work with in a Javascript environment than the typical alternative of XML. You always need to be cognizant of how much data you are forcing your user to retrieve on each call. I’ll leave it at that for now as a discussion of JSON vs. XML could be a blog post in its own right.

app.js

json.txt (from our target URL)

As you can see, we basically filled out the HTTPClient skeleton from above with the specific functionality of our app. With a successful response in onload we are going to parse the fighters JSON array via the JSON.parse() function. This returns a Javascript JSON array object through which we will iterate.

Each JSON object we find in the fighters JSON array represents a fighter with a name and nickname. We will create a custom Titanium.UI.TableViewRow that displays both of these values. In the end, we will have an app that looks like this:

Helpful Links

• Titanium.Network.HTTPClient API docs.
• Github repository for sample app