Integrating your web application with REST web services

Hi everyone,

In today's post I will walk you through the steps by which you can integrate your application to a web service. I will consider a web application and we will be using JQuery/JavaScript to achieve the same. However, most modern languages have libraries using which you can make HTTP requests.

For today's scenario I will be considering integrating our application with the OMDB API. It is a publicly available API which can be found here: http://omdbapi.com/ . It is developed by Brian Fritz and licensed under CC-BY 4.0. From the website, the OMDb API is a free web service to obtain movie information, all content and images on the site are contributed and maintained by our users.
The idea of our application is very simple; the user will enter the title of a movie, presses the search button and in case the movie exists, we shall populate the details of the movie on the page.
To achieve this we shall use HTML and JQuery.

Setting up the request

Firstly, we need to determine how we need to pass the request to the web service. In our case we need to pass our parameters in the URL itself. In some cases it might be needed to pass the necessary details in the request body. We can see the example in "Usage" section followed by the parameters section where the parameters are mentioned that needs to be populated while constructing the URL for the request. We can even try some interactive examples and see how we can search by title and how to specify the values the parameters. Here is a snapshot:

The encircled region shows the URL that needs to be generated. If you observe closely, you will see that the dynamics parts of the URL is where you specify the title of the movie, year of release, plot and response. Based on the documentation of the web service it is clear that only the title part is required in our case and everything else can be left as they will take the default values.
So in our case to construct the URL we will use this code:

var urlWithParameters = "http://www.omdbapi.com/?t=" + encodeURI(movieTitle) + "&y=&plot=short&r=json";

where movieTitle variables value comes from the search box input.

With the URL to hit now known, we can form the AJAX call as below:

var urlWithParameters = "http://www.omdbapi.com/?t=" + encodeURI(movieTitle) + "&y=&plot=short&r=json";
        $.ajax({
            url: urlWithParameters,
            method: "GET",
            dataType: "json",
            success: function (response) {
                populateUIWithResults(response);
            },
            error: function (jqXHR, textStatus, errorThrown) {
                alert("An error occurred: " + textStatus);
            }
        });

Working with the response

Once we know how to set up the request, the next step is to utilize the web service response and showing it in our UI. First we need to note in what format the response is received and how is the response formatted. We can observe it while we were setting up the request itself as to what is the format of the JSON response. I am attaching the same snapshot as the before one but highlighting the response region.

Most web-services will have documentation that will document the response format. In our case as we can see above the response is a plain JSON object.

We do not need to parse the JSON response as the framework will automatically convert the JSON response to a JavaScript object and we need to just read the properties of this JavaScript object and populate the values on the UI based on them. Here is the body of the populateUIWithResults(response) method that handles the response:

function populateUIWithResults(movieResponse) {
    if (movieResponse) {
        console.log("A response is received from the web service");
        if (movieResponse.Response) {
            $("#title").html(movieResponse.Title);
            $("#year").html(movieResponse.Year);
            $("#genre").html(movieResponse.Genre);
            $("#actors").html(movieResponse.Actors);
            $("#plot").html(movieResponse.Plot);
            $("#language").html(movieResponse.Language);
            $("#imdbRating").html(movieResponse.imdbRating);
            $("#duration").html(movieResponse.Runtime);
            $("#poster").attr("src",movieResponse.Poster);
        } else {
            alert(movieResponse.Error);
        }
    } else {
        console.log("No response is received from the web service");
        alert("No response is received from the web service")

    }

where all the identifiers marked with # are the IDs of the HTML span elements where the respective values will be stored. As you can see the respective properties of the JavaScript object are set as the inner HTML of the span tag in the HTML page.

The complete code for the implementation can be found here: http://webservicesintegration.codeplex.com

Here is a screen shot of the running application:

Thanks for reading my blog post. In case you have any questions or comments, please feel free to reach out to me in the comments section.

Cheers!