The power of the web comes from our ability to transfer data back and forth. Using RESTful web services is one of the ways that we can accomplish this task. Throughout this tutorial you will learn how to interact with a RESTful API and parse the data that comes back from the request. The Extensible Markup Language (XML) and JavaScript Object Notation (JSON) are two ways in which  the data that we receive can be formatted. While JSON is becoming the more popular format, this tutorial will show the use of both and how to parse each format. We will begin with a brief introduction to REST, and then move on to show how these services can be used.

REST stands for Representation State Transfer. REST is an architecture style that allows us to build lightweight and scalable web services. These services are called RESTful web services. Without getting to far into the weeds, these services allow us to send a request from our web application which will, in turn, send our application a response. For example, say you are ordering something on a web site and are being asked to choose a shipping method for the item. Now, for each shipping method the site is showing you what the price is for that method. How do they know what UPS, or any other carrier, will charge for this item. Well, the carrier has an API that allows the web application access to certain data to tell you, the user, what the cost will be for that method. And this is accomplished by the web application making a request to the API, receiving a response, and then parsing that response. Now, that we have a very brief overview of REST, let’s start by looking how this is used in action.

Below, you will see a simple HTML form. The form’s method is a GET, which will put our form information in the URL rather than the HTML header. Side note: For sensitive information we would use the POST method, which would send the form information in the header. Here, we have two simple inputs where a user can enter in a title of a book and the number of results that the user wishes to get back. We also have a button, which will call the GetBooks() method from within our main.js file. Below the form are a couple of textarea tags that we will use just for demonstration purposes. We will be making a request and getting the response back in XML and JSON. These two textarea tags will allow us to peek at the response as simple text, so as to show the difference. Now, let’s get into the meat of this subject by looking at the JavaScript below.

First, we get our user inputs when the button is clicked. The next few lines might look a little new. Here we are using the Yahoo API, a RESTful web service, that allows us to write a query in the Yahoo Query Language (YQL).  Here, we are basically using an intermediary that will perform the search on google.books. We are using this method, because if we interact directly with the Google Books API we would need to get an API key. So, while that would be necessary for a production application, for now we will use the Yahoo API for brevity.  The yqlBaseURL allows us to access the Yahoo API to use YQL. You will notice that for the yqlQuery, we use string concatentation to insert our user inputs into the query. Later we will tie these both together to send our request.

Next we create two new XMLHttpRequest objects. These objects are used to request data from a server, which is exactly what we want to accomplish. When the ready state changes for these two objects, it will call an anonymous function that will allow us to view our response in the two textarea tags that we created in our HTML.  Notice, that in the function we are using the “this” statement. The this statement in JavaScript, allows us to access the current context. In the case of our function, this.responseText would be the same as reqXML.responseText.  Notice, that for reqXML and reqJSON, we use the XMLHttpRequest.open(), and XMLHttpRequest.send() methods to send a request to the server. In the open method, we specify that the request is a GET with the first argument, and we pass in the yqlBaseURL and yqlQuery as the URL for the second argument. Notice the difference between the URL for the XML and the JSON request? In the JSON request, we are adding “&format=json” to the end of the URL. This is because, Yahoo default response is XML. To receive the response back as JSON we add this string at the end of the URL. This information is only obtainable through reading the documentation. The last argument is set to true, which makes the request asynchronous. The send method sends the request to the URL, and the response triggers our onreadystatechange anonymous function to be called.

Now that you have the HTML and JavaScript files written, give it a try. Open up the application in Google Chrome and open the dev tools. Go to the Network tab and click Preserve Log. In the Title text box type “beer”  and in the Maximum Results text box type “1”. Then click the Get Books button.  In the Network tab you will see the requests being called. Click on the first request. You can now see the request and response headers, as well as the query string. This is the request for the XML. Now, click the last request. Scroll to the bottom of the headers and look at the query string. Notice that the format is set to JSON. If you look in your two textareas, you will see the same information represented in two different formats, one for XML and one for JSON. Notice that they both brought back information regarding the same book, “The Foodie’s Beer Book” (at the time of this blog). Now these are a little hard to read since they are represented as text instead of their respective formats. Next week, I will introduce a tool that we can use to more easily examine these files.

So, now you have the basics of how to send and receive a response to a RESTful web service. With that, we unlock the true power of the web, and how we can send and receive data. Next week, we will dive more into the responses we got back from the server and how we can parse the data to make it useful. Until next week, go ahead and play around with JSON.parse, and see if you can figure out how to parse the JSON from the response. Remember to comment below if you have any questions, and share this post on your favorite social media platform.

One comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s