Using AJAX to Consume a REST Web API

Announcements

• How is the term project going?
  

Overview

This week you will learn how to create a web page that serves as a client to a REST web service. Your web page will use JavaScript and the DOM's XMLHttpRequest object to intereact with the web API.

• AJAX
• XMLHttpRequest
• Consuming a REST Service
• Development Tips
• Examples
• Further Exploration
  
• References

• AJAX (Asynchronous JavaScript and XML) lets you:
• Update a web page without reloading the page
• Receive data from a server - after the page has loaded
• Send data to a server - in the background

• Tutorial: MDN, AJAX Getting Started Guide
• For Practice: OpenWeatherMap API Docs

The XMLHttpRequest JavaScript object, which is part of the DOM in all modern browsers, lets you retrieve data from a URL without having to do a full page refresh. XMLHttpRequest was originally designed by Microsoft around 1999 and later adopted by Mozilla, Apple, and Google. Since October 2014, it has been part of the standard. Despite its name, XMLHttpRequest can be used to retrieve any type of data, not just XML, and it supports protocols other than HTTP (including file and ftp).

• Reference: MDN, XMLHttpRequest
  
• Guide: MDN, Using XMLHttpRequest
  
• Example:
  function responseListener () {
  console.log(this.responseText);
}

var oReq = new XMLHttpRequest();
oReq.addEventListener("load", responseListener);
oReq.open("GET", "http://www.example.org/example.txt");
oReq.send();

Follow the strategy for writing a REST client in JavaScript described in the tutorial by Geoffey Liu (2016).

• Watch out for cross-origin request issues - a potential "gotcha"!
• A cross-origin request is an HTTP request to a web service or web app that comes from some other domain than the one that hosts the service. Wikipedia: Cross-Origin Resource Sharing. Most web hosts will block Ajax requests (XMLHttpRequest) that come from another domain, but most hosting platforms provide a mechanism, CORS (Cross-Origin Resource Sharing), for selectively allowing requests from domains that you authorize.
• When testing your REST client against a Web API running on your development machine, you will need to put the client web page files into the wwwroot folder of your Web API project so that they will be served by your development server (IIS Express, Kestrel, etc.). Be sure to enable static files (see below).
• Enable static files in your Web API project.
• To enable your server to serve your REST client's web page, you need to enable static files by adding the line of code below to the Configure method in Startup.cs
  app.UseStaticFiles();
  
• Using a Web API running on Azure
  When testing your REST client against a Web API running on Azure, you can run your web client on your development machine if you enable CORS for the Web App running on Azure. To do this:
  1. Open the Azure Portal
  2. Click on App Service
  3. Scroll down the list of settings until you see CORS and click on it.
  4. Set an Allowed Origin.
     You can set the allowed origins to * so that your Web API can be called from any domain. (You may want to change this to be more restrictive when you have finished testing.)
     
     
  • Check your Web API for exceptions while running on Azure.
    To do this:
  1.  open the Azure Portal
  2. Click on App Service
  3. Scroll down the list of settings until you see Application Insights and click on it
  4. At the bottom of the page click on View more in Application Insights
  5. Scroll down in the new list on the left and click on Failures
  6. Near the top of the page, click on Exceptions

Examples

• Movie Catalog--Git repository
  Source code for both a REST web service and a client web page using AJAX.
• OpenWeatherMap Client--running online
  Web page with AJAX that gets current weather conditions from OpenWeatherMap.
• BookInfo Web API and Client--Git repository
  Source code for both a REST web service and a client web page using AJAX.
• BookInfo Web API Client--running online
  Web page with AJAX that interacts with the BookInfo web service running online.

Further Exploration

Fetch vs. XHR

Newer JavaScript web clients use the fetch() method rather than the older XMLHttpRequest() (XHR) method. Both methods are asynchronous, but fetch uses promises rather than the older style JavaScript call-backs.

Newer protocols for communication over the web

There are several modern alternatives to REST or SOAP for communicating with a web API. Two of them are:

• gRPC—A protocol developed by Google that is becoming an industry standard.
• SignalR—A protocol and ASP.NET/ASP.NET Core library developed by Microsoft that enables real-time communication between a web app and a web API.
  

References

• "Ajax," on MDN Web Docs. The Mozilla Foundation.
• Liu, Geoffrey. (2016). "A strategy for consuming REST API’s in JavaScript," on The Thought Box
• JS AJAX on W3Schools. Refsnes Data.
• Weather API on OpenWeatherMap. OpenWeather Ltd.