API Development

Consuming Web Services

In a previous post I talked about a library that makes it super easy to communicate with web services. In this post, I’ll step back a little bit, explain what exactly a web service is, and go through the process of consuming data from them.

Understanding web services

By its name, a Web service can be any service that is accessed through a web browser, such as Dropbox, Evernote or Gmail. However in software terms, a web service is a program that you can interact with through a network call. In modern web applications, developers have implemented groups of web services called APIs (Application Programming Interface). The concept of an API is not new and it’s not exclusive to web or mobile programming, but I’ll only talk about its application to web and mobile technology.

Ten years ago the idea of having data available for consumption by third-parties was not common, in fact it was avoided at all costs. Companies adopted the approach of “my data is my data, and it’s my competitive advantage”. Today, we have seen that providing access to data is an essential part of companies like Facebook and Twitter. For them, having an API is a way of expanding the reach of their services, increasing engagement, innovation and adoption. Even governments have embraced the use of APIs in order to speed up the development of web and mobile apps for their citizens.

JSON

JSON, or Javascript Object Notation is the data structure of preference for today’s web services. As opposed to its counterpart XML, JSON provides a much leaner way of structuring data, ideal for data transfer over mobile networks.

The beauty of a web service is that it provides an agnostic way of transferring data over the Internet that is both platform-independent and language-independent. Every computer language has a string data-type. With JSON you transfer an object in string format and the receiver converts it back to a native data structure. That’s why you can have a web service written in Python and consume it from Javascript, or one written in PHP and consume it from VB.NET. There’s a JSON implementation for virtually all modern programming languages, but its home base is Javascript.

Why is JSON so important

The combination of Javascript objects and arrays make JSON strings multi-dimensional. The JSON string can either start as an object or as an array depending on the design of the web service, but nesting them is what makes this format so versatile. However, at the same time, as JSON files get more complex, they become difficult to read. This is normal, so don’t feel overwhelmed. In fact, you’re not supposed to be able to read it; JSON was designed to be consumed by computers. I’ll explain more technical details about Javascript object and arrays in a future post.

HTTP GET and POST

The two most important methods for HTTP communications are GET and POST, GET being the default. You perform a GET every time you call a URL. Although you can send data through a GET call, it’s usually data that will be used as contextual information to retrieve more data. You perform a POST every time you send data to a web service, such as filling out a form. The POST method encodes the data in a different way, providing more security and allowing you to send more data in each request.

Consuming data

If you’re going to be working with JSON, you will need some tools to help you along the way. In my opinion, the most important of these is the JSONView extension for your browser. This extension will allow you to view JSON files not as a block of unreadable text, but as a hierarchical structure. Although this extension was originally developed for Firefox, there is a port for Google Chrome that adds a the feature of automatically displaying your Javascript array/object path. Head over to https://jsonview.com and install the extension on your browser. Browse to your JSON endpoint (URL) and see what happens. In this example I’m browsing to https://api.twitter.com/1/statuses/user_timeline.json?include_entities=true&include_rts=true&screen_name=appcelerator&count=20.

You’ll see the JSON string neatly formatted. Also, notice that you can collapse and expand each branch. Last but not least, hover over any of the entries and see how it displays on the status bar the path to use on your Javascript code. In this example [0].text refers to the “text” property on the item “0” of your array.

With the XHR library described earlier, you perform a HTTP GET call with a single line.

xhr.get(url, onSuccessCallback, onErrorCallback, options);

The callbacks are simply functions you send to the library to be used later on, in this case when the process was successful or when there was an error. Note that you need to define these functions before calling the GET or POST method.

Let’s examine the onSuccessCallback.

When you receive the data in the variable e, we run the JSON.parse method on the data property. This will create a native Javascript object in the variable response. Since we had previously examined the response using JSONView, we know it is an array, so can then loop through all the items. Inside each array element, there’s a complex object. Using dot notation we extract each of the properties from the object. Run this code and you’ll get tweets in individual variables, ready to be used as needed.

Studio console

To perform a HTTP POST, you simply add an additional parameter to the POST method. Testing POST is a little bit different though, because sometimes there’s really not feedback from the server. Time for another cool tool that might help you. To test HTTP POST calls before actually hooking into my actual web service, I use https://www.posttestserver.com/ as my endpoint. This website is just sitting there waiting for HTTP POST calls, naturally for testing purposes. The POST data is sent to the XHR library as a regular Javascript object. The values you’re assigning to the payload variable are equivalent to the values on an HTML form, so if you’re interacting with PHP code to submit a form, this variable holds the values of each form field.

The POST server website will confirm that it indeed received the data and will give you a URL to view the data received. Remember, this is a public website so only use it to send test data.

Post response

Once you know that your data is being properly received by the “post server”, then you know that your app is working properly, so not switch the post call to the actual one and you’re set.

Now that you can communicate with web services, the next step is to do something useful with the data. By combining Appcelerator Alloy with this very basic example, you can have a native interface to read tweets. You can see all the required files here: https://gist.github.com/ricardoalcocer/5190529. Here’s what it looks like.

Want some homework? Why don’t you implement the “Post a tweet” functionality?

In a final post of this series, I’ll explain how to create your own web services using Appcelerator Cloud Services. Stay tuned.