How to Connect to an External API with JavaScript

Note: This is part 3 of three-part How to Make HTTP Request in JavaScript series. This learning post is still in active development and updated regularly.

In this three-part How to Make HTTP Request in JavaScript series, introduction to JSON, working with JSON data, and connecting to external API to obtain JSON data from servers, and their use in web pages will be discussed.

Posts Series:
Part 1: Deep Diving into JSON and Its Use in JavaScript
Part 2: Working with JSON Data and Common Use Case Examples
Part 3: How to Connect to an External API with JavaScript (this post)

In the previous posts (part 1 & part 2), introduction to JSON basics, JSON data types & syntax, simple use case examples of JSON as objects or arrays and use of XMLHttpRequest, Fetch API and JQuery to read locally stored JSON file were discussed.

In the previous post reading external JSON file using XMLHttpRequest (XHR) and Fetch API were discussed in passing. In this post, an brief overview of Web API, XHR, Fetch API and their basic use in accessing data from external API with simple example cases and displaying JSON data in a HTML document is discussed. A more detailed post Understanding Web API and Fetching Data From Remote servers is discussed separately.

A prior knowledge of HTTP protocol, Web API, XHR, Fetch API and their use in data exchange from external API is essential for a better understanding of how data are accessed from external servers.

An Overview Of Fetching Data from Servers

The HTTP protocol is serves as the foundation of exchanging documents in the internet.

The Web API

The word API stands for (Application Programming Interface). The API are commonly used in our daily life (eg. computer OS, electric plugs, computer mouse, etc.). It is short of lawyer saving time to understand all the details in a complicated legal contract agreement.

The web API likewise is a web service (eg. email system, face book, twitter, word processing, etc.). They abstract more complex code away from you, providing some easier syntax to use in its place (MDN).  One of the commonly used web API include REST, RESTful and other browser API or third-party API (eg. Twitter API).

Commonly used browser API include: DOM API which allows document manipulation, API that fetches data from web servers like XMLHttRequest and Fetch API and many others.

Additional Information: Introduction to web APIsIntroduction to web APIs | MDN Web Docs

The XMLHttpRequest API

The XMLHttRequest (XHR) requests can be made in two ways, synchronously and asynchronously. In early days, it was known as AJAX (Asynchronous JavaScript and XML) because its was primary used in XML data request but these days it is used to data exchange in JSON and plain text too.

The XHR allows “web pages to directly handle making HTTP requests for specific resources available on a server and formatting the resulting data as needed before it is displayed“.

A basic XHR request looks like as shown below:

// Create a request variable and assign a new XMLHttpRequest object to it.
var request = new XMLHttpRequest();

// Open a new connection, using the GET request on the URL endpoint
request.open('GET', 'url', true);
//called after the response is received
request.onload = function () {
  // Begin accessing JSON data here
  }
}
// Send request
request.send();

The basic steps in making XHR request:

Step 1: Make a new XHR request by creating a new new XMLHttpRequest constructor object and assign it a new variable (eg, request, can be any name; line 2).

Step 2: Specify HTTP request method to make request from the network resource (eg, URL) using open() method (Line 5) and pass commonly used method GET and URL as variables.

Step 3: The expected response can be defined using responseType property such as text, json, etc. It is not required but is a good practice.

Step 4: Accessing network data through the XHR is asynchronous, its response is handled using onload event handler. When the response is loaded, then only the data is available for processing (line 7). If request is not completed it returns status property code, for example 200 = OK,  404 = Not found, and 403 = forbidden.  For a complete list visit Http Messages Reference.

Step 5: Make a send request over the network using .send() method (line 12), without the XHR request does not run.

The XMLHttpRequest is most commonly used built-in browser request method. The other more powerful and flexible Fetch API can be used for making similar request.

The Fetch API

The Fetch API is a XHR replacement introduced recently to make asynchronous HTTP request easier. It has simpler, flexible yet robust feature and returns ES6 based Promise. The fetch() function takes a endpoint URL (required parameter).

The basic structure of Fetch API request looks as shown below:

//ES5 Syntax
// request to API
fetch('url').then(function (response) {
  return response.json();
}).then(function (data) {
  // work with JSON data here
  console.log(data);
}).catch(function (err) {// error message
});

The above snippets using ES6 syntax is even simpler:

// request to API
fetch(url').then(response => {
  return response.json();
}).then(data => {
  // work with JSON data here
  console.log(data);
}).catch(err => {
  // error message
});

The basic steps in the Fetch request methods:

Step 1: Invokefetch() method and pass source URL of the remote server. This is equivalent to calling request.open() in XHR. In Fetch method does not require .send() method equivalent used in XHR.

Step 2: Chain with .then() method onto the end of the fetch() method (line 3, 10) as part of Promise. The .then() method is used to run follow up codes as a function after promise is resolved. This is equivalent to onload event handler in XHR.

Step 3: When Fetch() promise is resolved, the returned response is grabbed and run specified function [eg. .then(function() { .. }) ]. Optionally, a return statement can be added in front of response object in a desired format, for examlpe: response.json() or response.text() to get it to pass its result on to the next link in the chain (line: 4, 12). This is equivalent of request.responseType = 'text' in the XHR.

Step 4: The response object method returns a promise, resulting in a JSON format with json() or text string with text() which can be chained with .then() method for further processing (line: 5, 13).

Step 5: Inside the inner promise function (line 5, 12) is similar to XHR.

Step 6: To handle errors, a .catch() block (lines: 8-9, 16-18) can be chained onto the end of the chain and runs only if promise is failed.

Note: A deep dive understanding in Web API, commonly used API based HTTP (XMLHttpRequest and Fetch API) is essential to use them in accessing data from external API / remote servers.

Using XMLHttpRequest API

In the example below, the XMLHttpRequest API call is used to access users name from the jsonplaceholder API. Clicking on https://jsonplaceholder.typicode.com/users in browser address bar displays arrays of objects as JSON.

Retrieving Data from API Endpoint

Using the XMLHttpRequest API protocol described in previous section, the url (line 4) is replaced by the jsonplaceholder API url: https://jsonplaceholder.typicode.com/users as API endpoint. When the request is completed, the requested data are loaded onload() function (line 5). After processing the JSON data, the request.send() method is issued at the end (line 19).

//using XHR to display list of users
var request = new XMLHttpRequest();

request.open('GET','https://jsonplaceholder.typicode.com/users', true);
request.onload = function () {

  // Begin accessing JSON data here
  var data = JSON.parse(this.response);

  if (request.status >= 200 && request.status < 400) {
    data.forEach(users => {
      console.log(users);
    });
  } else {
    console.log('error');
  }
}
//
request.send()
JSON Response Data

The HTTP request response is delivered in JSON format which needs to be converted to JS objects using JSON.parse() function and stored in a variable named data (line 8) as an array of JS object. In lines 10-13, users ID between 200 and 400 (line 10) will be displayed in browser console using using forEach() loop (line 11).

If some something goes wrong, the script throws an error message (lines: 14-16).

Displaying Retrieved JSON Data

Displaying received JSON Data requires knowledge of the DOM manipulation and will be discussed in a separate post. A brief discussion is available in this Tania Rascia’s post.

In the example below, displaying JSON data in the browser console are briefly discussed. In the example below, retrieved data from user id=1 is displayed as an array in JSON object.

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
     }
  },
  ..
  ..
  }
 ]

In the example output (partial), data retrieved from userid 1 as JSON array are displayed in browser console (shown only one user) as JSON property & values.

Limiting JSON Data Display Properties

To limit display JSON data properties in the output, the above snippets (lines: 11-13) can be modified as below to only display user name, email & website properties values as shown below:

// only partial code
 data.forEach(users => {
      console.log(users.name);
      console.log(users.email);
      console.log(users.website);
    });
//..
..
//OUTPUT
Leanne Graham
Sincere@april.biz
hildegard.org
Ervin Howell
Shanna@melissa.tv
anastasia.net
..
..

In the example above, the partial (two) output (lines: 9-15) of users name, email and website is displayed in the browser console, as expected.

Limiting Number of Items to be Retrieved

Number of retrieved items (eg. users in this example) can be limited modifying query (as described in this forum) as shown below:

// how to limit number of users displayed
http://jsonplaceholder.typicode.com/users?_start=1&_limit=20

Note: The XMLHttpRequest method described above was inspired by Tania’s post How to Connect to an API with JavaScript.

Using Fetch API

The use case example of using Fetch API to make HTTP request from JSONPlaceholder to get users data is shown in the example below:

// Using Ftch Api
fetch('https://jsonplaceholder.typicode.com/users').then(response => {
  return response.json(); // define the response type (eg. json, text)
}).then(data => { // get the response type
  // Work with JSON data here
  console.log(data);
}).catch(err => {
  // Do something for an error here
   console.log('err');
});

The above code snippets uses Fetch API and makes a call to jsonplaceholder to fetch lists of user data (line 2) and outputs the following users data as JSON object in your browser console.

As described earlier in the Fetch API, to access the returned data two .then() callback methods are required (lines: 3, 4), first then() callback (line 3) to access the return and the second .then() callback (line 4) to get the requested data and to display in the console (line 6), in the example above. In the example, if users in jsonplaceholder API is not defined it displays default value of 10 users.

Figure: Screenshot of Fetch API shown as extracted JSON object from the response body
Limiting Number of Items to be Retrieved

To limit number of users (five only) and display their name and e-mail address only, the above code snippets could be modified as below:

//using Fetch Api
fetch('https://jsonplaceholder.typicode.com/users?_start=1&_limit=5')
 .then(response => {
  return response.json();
}).then(data => {
  // Work with JSON data here
 for (var i = 0; i < data.length; i++) {
 console.log(data[i].name + ' and Email: ' + data[i].email + '.');
}}).catch(err => {
  // Do something for an error here
  console.log('err');
});

//OUTPUT
Leanne Graham and Email: Sincere@april.biz.
Ervin Howell and Email: Shanna@melissa.tv.
Clementine Bauch and Email: Nathan@yesenia.net.
Patricia Lebsack and Email: Julianne.OConner@kory.org.
Chelsey Dietrich and Email: Lucio_Hettinger@annie.ca.

In the example above, to output only list of five users, the users/ field in line 12 was modified as users?_start=1&_limit=5 as explain in this forum. To display only name & e-mail, the JSON data were modified using for loop (lines: 15-18) as shown above. The code snippets displays list of five users name and email as shown in the output (lines: 23-28).

Additional Information: The Fetch API by Swapnil Bangare | Medium

Wrapping Up

In the previous posts (part1 & par2) on this series, introduction to JSON, its data types and common use case examples were discussed. In this (part 3) learning-note post, an brief overview of Web API, XHR, Fetch API and their basic use in accessing data from external API with simple example cases is discussed. Displaying JSON data in a HTML document, requires prior knowledge of understanding of DOM, will be discussed in separate posts.

Next Post: Displaying JSON data in a HTML document

Useful Resources and Links

While preparing this post, I have referred the following references extensively. Please to refer original posts for more detailed information.