Fetch API

• Getting data from an API or from a database is a tree-stap action
  1. Calling the fetch() methode to starts a request
     The fetch() methode returns a promise (see later in this course)
  2. When the request completes, the promise resolves a response object
  3. This response returns a lot of information, but the actual data can be extracted in JSON format (with response.json()) or in raw text (with response.text())
• The response of the fetch() methode will pass through the chain (one or more) of .then() handlers to process the data and a .catch() handler to process the errors
  fetch().then().then().then().catch();

IMPORTANT

• Every .then() handlers MUST returns something so it can be used as input data for the next .then() handler
• With the the fetch() methode, the first .then() handlers always must returns response.json() (if the response is in JSON format) or response.text() (if the response is just raw text)

• fetch() can handle all the different HTTP verb methodes (opens new window) you can expect from a CRUD (Create, Read, Update and Delete)

verb (methode)	action	description
GET	read	get date from an API, database, ...
POST	create	post date to an API, add data to a database, ...
PATCH/PUT	update	update a record in the database, ...
DELETE	delete	delete a record from the database, ...

• The fetch(url, options) methode accept two parameters:
  • url: the URL to fetch from
  • options: some optional parameters
• A full description of all options can be found here (opens new window)
  The ones you use the most are:

option	possible values
method	GET (default), POST, PUT, DELETE, ...
headers	'Content-Type': 'application/json', ...
body	JSON.stringify(data), ... (data type must match Content-Type header)

Basic HTTP verbs

• To demonstrate a very basic example of the different verbs, we use the https://reqres.in/ (opens new window) API
• This is a fake API where the create, update and delete actions are not actually taking place, but the response 'fakes' this is really happens

GET

• Use the get methode to retrieve data from an API or from a database
• You don't have to explicitly set this methode, because this is the default methode when for fetch()
• To retrieve information with fetch(), you only have to pass the URL as a parameter
• Open es6/fetch/get.html and es6/fetch/get.js
• This example gets all the users on page 2 with this URL: https://reqres.in/api/users?page=2 (opens new window)
• We are only interested in the key data witch contains an array of six users

<div class="border-gray row" id="users"></div>

• Line 8: the fist then() must return response.json() so this data can be uses in the next then()
• Line 14 to line 25: inside the second then(), we loop over the data[] array to construct some cards and add them to the page
• Line 27: if there is a network error, show the error message in the console

const url = 'https://reqres.in/api/users?page=2';

function getUsers() {
    fetch(url)
        .then((response) => {
            console.log('response', response);
            // the first then() always returns response.json()
            return response.json();
        })
        .then((users) => {
            console.log('users', users);
            let cards = '';
            // users.data[] contains 6 users
            users.data.forEach((user) => {
                cards += `
                    <div class="card">
                      <img src="${user.avatar}" class="section media">
                      <div class="section">
                        <p>${user.first_name} ${user.last_name}<br>
                        <a href="mailto:${user.email}">${user.email}</a>
                        </p>
                      </div>
                    </div>`;
            });
            document.getElementById('users').innerHTML = cards;
        })
        .catch((error) => console.log(error));
}
getUsers();

POST

• Use the POST methode to send new data to an API or insert something in a database
• The data that will be sent to the API and the methode (POST) are past to the options parameters of the fetch() methode
• Open es6/fetch/post.html and es6/fetch/post.js

<div class="border-gray row" id="user"></div>

• Line 2 to line 7: create an object that contains a new user
• Line 10 to line 16: set the required options to post the new user to the API
• Line 20: the API sends us the newly (fake) inserted user
• Line 23 to line 31: show a card of the new user on the page

// new user object
const newUser = {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    avatar: 'https://images.freecreatives.com/wp-content/uploads/2017/01/Person-Icons.jpg',
};
const url = 'https://reqres.in/api/users';
// options for the fetch() methode
const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(newUser),
};

function postUser() {
    fetch(url, options)
        .then((response) => response.json())
        .then((user) => {
            console.log('user', user);
            document.getElementById('user').innerHTML = `
              <div class="card">
                <img src="${user.avatar}" class="section media">
                <div class="section">
                    <p>${user.first_name} ${user.last_name}<br>
                    <a href="mailto:${user.email}">${user.email}</a>
                    </p>
                </div>
            </div>`;
        })
        .catch((error) => console.log(error));
}
postUser();

PATCH/PUT

• Use the PATCH (or PUT) methode to update data through an API or update something in a database
• The data that will be sent to the API and the methode (PATCH) are past to the options parameters of the fetch() methode
• Open es6/fetch/patch.html and es6/fetch/patch.js

<div class="border-gray row" id="user"></div>

• The only real difference in this script is the URL (line 8) and the methode (line 11)

// new user object
const newUser = {
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    avatar: 'https://images.freecreatives.com/wp-content/uploads/2017/01/Person-Icons.jpg',
};
const url = 'https://reqres.in/api/users';
// options for the fetch() methode
const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(newUser),
};

function postUser() {
    fetch(url, options)
        .then((response) => response.json())
        .then((user) => {
            console.log('user', user);
            document.getElementById('user').innerHTML = `
              <div class="card">
                <img src="${user.avatar}" class="section media">
                <div class="section">
                    <p>${user.first_name} ${user.last_name}<br>
                    <a href="mailto:${user.email}">${user.email}</a>
                    </p>
                </div>
            </div>`;
        })
        .catch((error) => console.log(error));
}
postUser();

DELETE

• Use the DELETE methode to delete data through an API or delete something from a database
• The methode (DELETE) is past to the options parameters of the fetch() methode
• Open es6/fetch/delete.html and es6/fetch/delete.js

<div class="border-gray row" id="user"></div>

• Notice that when we look at the DELETE example on the API (opens new window), we only gets a status code 204 (opens new window) back
• The status code is available through the response.status property
• Line 11 to line 13: show some feedback on the page if the status code is 204

const url = 'https://reqres.in/api/users/7';
// options for the fetch() methode
const options = {
    method: 'DELETE',
};

function deleteUser() {
    fetch(url, options)
        .then((response) => {
            console.log('response', response);
            if (response.status === 204) {
                document.getElementById('user').innerHTML = 'User successfully deleted';
            }
        })
        .catch((error) => console.log(error));
}
deleteUser();

Error handling

• The fetch() promise will reject (trow an error that will be handled bij thecatch()) handler ONLY if:
  • a network error occurs
  • a CORS (opens new window) header is sent by the server
  • the base URL don't exists
• In every other situation e.g: faulty parameters on the URL, access not allowed, etc... the fetch() promise will resolve, and you have to deal with these kind of errors yourself
• This can be easily done within the first then() handler, just before returning response.json()
• When we look at the response object (opens new window), there are tree properties we can use to test the status of the response (look at the result tab on the GET and the DELETE example)

property	description
status	status code (opens new window) e.g: 200 (ok), 404 (not found), 403 (forbidden), ...
ok	true if status code is in the range of 2xx otherwise false
statusText	which corresponds to the HTTP status code (but most of the time this string is empty)

• Now you can trow an error if response.ok is false, else sent response.json() to the next then() handler
• Some possible scenarios to respond to an error:

• if response.ok is false, trow a new Error object and let the catch() handler do the rest

fetch(url, options)
    .then((response) => {
        if (!response.ok) {
            throw Error(`Fetch error code ${response.status}`);
        }
        return response.json();  //we only get here if there is no error
    })
    .then((res) => {
        // do something with the response
    })
    .catch((error) => console.error(error));

• if response.ok is false, send a customised message to the catch() handler

fetch(url, options)
    .then((response) => {
        if (!response.ok) {
            if (response.status === 403) throw Error(`You don't have access to this file`);
            if (response.status === 404) throw Error('The requested file was not found');
            // add some other status codes ...
            throw Error('Something went wrong with your request');
        }
        return response.json();  //we only get here if there is no error
    })
    .then((res) => {
        // do something with the response
    })
    .catch((error) => console.error(error));

• Open es6/fetch/error.html and es6/fetch/error.js
• This time we use jsonplaceholder (opens new window), another frequently uses fake API
• Open the console and look what's inside response.ok, response.code and the error message

const url = 'https://jsonplaceholder.typicode.com/users/1';
// const url = 'https://jsonplaceholder.typicode.com/users/1111111';
// const url = 'https://nonexistingurl.com/users/1';

function getUser() {
    fetch(url)
        .then((response) => {
            console.log('response', response);
            if (!response.ok) {
                if (response.status === 404) throw Error('The requested user was not found');
                throw Error('Something went wrong with your request');
            }
            return response.json();
        })
        .then((user) => {
            console.log('User found', user);
        })
        .catch((error) => {
            console.error(error);
        });
}
getUser();

• The URL exists so there is no error message
  

• Change URL to a non-existing user: https://jsonplaceholder.typicode.com/users/1111111
  

• Change URL to a non-existing URL: https://nonexistingurl.com/users/1
  

Preloader

• Fetching data from an API sometimes takes a few seconds
• It's always a good idea to show your visitors some kind visual information that something is happening in the background
• This can be in the form af a preloader, a pinner or a simple text message
• Show the preloader just before fetching the data and hide the preloader when the data is rendered to the page or when an error occurred

function getUser() {
    fetch(url, options)
        .then((response) => { ... })
        .then((res) => {
            // do something with the response
            preloader.style.display = 'none'
        })
        .catch((error) => {
            console.error(error);
            preloader.style.display = 'none'
        });
}
preloader.style.display = 'block';
getUser();

Examples

As we will not be using a backend of our own in this course, we will only discuss examples where we are retrieving data from external API's

Fetch images

• Open /es6/fetch/images.html and /es6/fetch/images.js
• In this example we fetch all images from our own (fake) API:
  https://my-json-server.typicode.com/pverhaert/itf-api/picsum (opens new window)

<div class="spinner tertiary"></div>
<div class="row" id="imgContainer"></div>

• Line 5: fetch the API and check if there is an error
• Line 8 to line 10: check if the response has some errors
• Line 12: extract the JSON data from the response and sent the result to teh next then()
• Line 16 to line 29: then() loop over every item inside the array, construct a card (opens new window) with the data and append it to the #imgContainer
• Line 31: then() hide the spinner and send the data to the caller function

const url = 'https://my-json-server.typicode.com/pverhaert/itf-api/picsum';
const spinner = document.querySelector('.spinner');

function fetchImages() {
    fetch(url)
        .then((response) => {
            // check for errors
            if (!response.ok) {
                throw new Error(`An error has occurred: ${response.status}  ${response.statusText}`); // check for errors
            }
            // return JSON data
            return response.json();
        })
        .then((images) => {
            // add a card for every image in the array images[]
            images.forEach((image) => {
                document.getElementById('imgContainer').innerHTML += `
                    <div class="card">
                      <img src="${image.url}/600/400" class="section media" alt="Image by ${image.author}">
                      <div class="section">
                        Image &copy; <a href="https://unsplash.com/photos/${image.meta.unsplash}" target="_blank">${image.author}</a>
                        <br>
                        Category: ${image.category}
                      </div>
                    </div>
                `;
            });
        })
        .then(() => {
            // hide the spinner
            spinner.classList.add('hidden');
        })
        .catch((error) => {
            spinner.classList.add('hidden');
            console.log(error);
        });
}
fetchImages();

Fetch movie info

• Open /es6/fetch/omdb.html and /es6/fetch/omdb.js
• Serialize form (opens new window)
• In this example we fetch movie information from the OMDb API (opens new window)
• The parameters we needed are:
  • apikey: your API key (you must first generate a free apikey (opens new window))
  • t: the movie title to search for
  • y: year of release
  • plot: can be full or short
• The JSON we get from te server: https://www.omdbapi.com/?apikey=yourKey&t=Pulp+fiction&y=&plot=short (opens new window)
  (Replace yourKey in the query string with a real API key)

• line 2: replace the value for apikey with your API key
• As you can see in the form, the name attribute of the form elements matches exactly the keys for the query string we have to append to the fetch URL
• This makes it super easy (only three lines of code) to serialize the form (opens new window) with JavaScript
  The result of this serialization is a string like this: apikey=yourKey&t=Pulp+fiction&y=&plot=short

<form>
    <input type="hidden" name="apikey" value="yourKey" />
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="title" class="doc">Title</label></div>
        <div class="col-sm-12 col-md">
            <input type="text" placeholder="Title" id="title" name="t" value="Pulp fiction" required />
        </div>
    </div>
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="year">Year</label></div>
        <div class="col-sm-12 col-md">
            <input type="number" placeholder="Year" id="year" name="y" />
        </div>
    </div>
    <div class="row responsive-label">
        <div class="col-sm-12 col-md-2"><label for="plot">Plot</label></div>
        <div class="col-sm-12 col-md">
            <select id="plot" name="plot">
                <option value="short">short</option>
                <option value="full">full</option>
            </select>
            <button type="submit" class="primary">Search</button>
        </div>
    </div>
</form>
<hr />
<div class="spinner tertiary"></div>
<div class="row" id="movieContainer"></div>

• Line 61: submit the form when the page is loaded
• Line 54 to line 59: serialize the form and append it to the fetch URL
  Result: fetchMovie('https://www.omdbapi.com/?apikey=yourKey&t=Pulp+fiction&y=&plot=short');
• The rest of the code follows just the same logic as the code in the previous exercise

const omdbapi = 'https://www.omdbapi.com/';
const spinner = document.querySelector('.spinner');
const form = document.querySelector('form');

function fetchMovie(url) {
    console.log(url);
    fetch(url)
        .then((response) => {
            // check for errors
            if (!response.ok) {
                throw new Error(`An error has occurred: ${response.status}  ${response.statusText}`); // check for errors
            }
            // return JSON data
            return response.json();
        })
        .then((movie) => {
            // info if movie not found
            let info = `
                  <div class="card warning full-width">
                    <p>No info found for <b>${title.value}</b></p>
                  </div>`;
            // overwrite info if the movie is found
            if (movie.Response === 'True') {
                const poster = movie.Poster && movie.Poster.length > 10 ? `<img src="${movie.Poster}">` : '';
                info = `
                    <div class="row">
                      <div class="col-sm-6">${poster}</div>
                      <div class="col-sm-6">
                        <h2>${movie.Title}</h2>
                        <p><b>Genre: </b>${movie.Genre}<br>
                        <b>Released: </b>${movie.Released}<br>
                        <b>Actors: </b>${movie.Actors}<br>
                        <b>Director: </b>${movie.Director}<br></p>
                        <hr>
                        <p class="text-justify">${movie.Plot}</p>
                      </div>
                    </div>`;
            }
            document.getElementById('movieContainer').innerHTML = info;
        })
        .then(() => {
            // hide the spinner
            spinner.classList.add('hidden');
        })
        .catch((error) => {
            spinner.classList.add('hidden');
            console.log(error);
        });
}

form.addEventListener('submit', (e) => {
    e.preventDefault();
    // get all field data from the form
    const data = new FormData(form);
    // convert data to a query string
    const queryString = new URLSearchParams(data).toString();
    // console.log(queryString);
    // fetch data from OMDb
    fetchMovie(`${omdbapi}?${queryString}`);
});
form.dispatchEvent(new Event('submit'));

Belgian railway schedules (advanced)

• Open es6/fetch/irail.html and es6/fetch/irail.js
• For this example we our exact location and two API cals
  • Use the Geolocation API to get your exact location
  • Grab a list of all Belgian railway stations from https://api.irail.be/stations/?format=json&lang=en (opens new window)
  • Grab a timetable from one of your closest railway stations
    E.g: the railway station of Geel has an id of BE.NMBS.008832433
    https://api.irail.be/liveboard/?id=BE.NMBS.008832433&format=json&lang=en (opens new window)

<!DOCTYPE html>
<html lang="en">
    <head>
        ...
        <style>
            #preloader {
                display: flex;
            }
            #timetable div span:first-child {
                font-family: monospace;
            }
            #timetable div span:nth-child(2) {
                display: inline-block;
                font-family: monospace;
                width: 35px;
                text-align: center;
                font-weight: bold;
                color: darkred;
            }
            #timetable div span:nth-child(3) {
                display: inline-block;
                width: 30px;
                text-align: center;
                margin: 0 0.5rem;
                background-color: darkslategray;
                color: white;
            }
        </style>
    </head>
    <body>
        ...
        <div id="preloader">
            <div class="spinner tertiary"></div>
            <p>loading...</p>
        </div>
        <div id="buttons"></div>
        <h3 id="station"></h3>
        <div id="timetable"></div>
       ...
    </body>
</html>

• Line 12 get your location and add your coordinates to the myLocation object
• Line 19 call the function fetchStations()
• Line 37 fetch a list of all railway stations and return the JSON data
  • Line 42 then() calculate for every station the distance between your coordinates, and the station coordinates
    Use the map() methode to add the distance to every object in the stations[] array (The mathematical calculation behind this (line 146) is beyond the scope of this course)
  • Line 61 then() order the stations[] array from near to far from your location
  • Line 67 then() get the five closest railway stations, add for every station a button on te page and ad an event listener to it
  • Line 85 then() trigger click event on first button
• Line 81, line 97 and line 98 click on one of the five buttons to fetch the liveboard (timetable) for this station and return the JSON data
  • Line 99 then() filter the departure from the request and use the map() methode to transform every item (recalculate delay, add a class for the layout, ...)
  • Line 124 then()` add the modified liveboard to the page and hide the preloader

const buttons = document.getElementById('buttons');
const preloader = document.getElementById('preloader');
const stationsUrl = 'https://api.irail.be/stations/?format=json&lang=en';
let closestStations = [];
// default value for myLocation = Geel
const myLocation = {
    lat: 51.162074,
    lng: 4.99088,
};

// get current position
if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(
        (position) => {
            // update myLocation
            myLocation.lat = position.coords.latitude;
            myLocation.lng = position.coords.longitude;
            // fetch all Belgian railway stations
            fetchStations();
        },
        (error) => {
            alert('Unable to retrieve your location');
        },
        {
            enableHighAccuracy: true,
            timeout: 3000,
        }
    );
} else {
    alert('Geolocation is not supported by this browser');
}

function fetchStations() {
    // fetch all Belgian railway stations
    preloader.style.visibility = 'visible';
    preloader.querySelector('p').textContent = 'Loading stations ...';
    fetch(stationsUrl)
        .then((response) =>
            // return JSON part of the response
            response.json()
        )
        .then((stations) => {
            console.log('unordered list of railway stations', stations);
            preloader.querySelector('p').textContent = 'Find closest station ...';
            // modify the properties of every station
            return stations.station.map((st) => {
                // convert lat and lng form string to number
                const lat = +st.locationY;
                const lng = +st.locationX;
                // calculate the distance between your location and the station location as the crow flies (in km)
                const distance = calcCrow(lat, lng, myLocation.lat, myLocation.lng);
                return {
                    lat,
                    lng,
                    distance,
                    id: st.id,
                    name: st.name,
                };
            });
        })
        .then((stations) => {
            // order railway stations by distance from your location
            const ordered = stations.sort((a, b) => a.distance - b.distance);
            console.log('ordered list of railway stations', ordered);
            return ordered;
        })
        .then((orderedStations) => {
            // get the five closest railway stations
            closestStations = orderedStations.slice(0, 5);
            console.table(closestStations);
            // add a button for every station
            closestStations.forEach((station) => {
                buttons.innerHTML += `<button data-id="${station.id}">${station.name}</button>`;
            });
            // add event listener to every button
            buttons.querySelectorAll('button').forEach((button) => {
                button.addEventListener('click', function (e) {
                    const id = this.dataset.id;
                    document.getElementById('station').textContent = this.textContent;
                    // get timetable from the clicked station
                    fetchTimetable(id, this.textContent);
                });
            });
            // trigger click event on first button
            buttons.querySelector('button:first-child').dispatchEvent(new Event('click'));
            preloader.style.visibility = 'hidden';
        })
        .catch((error) => {
            console.log(error);
        });
}

function fetchTimetable(id, station) {
    preloader.style.visibility = 'visible';
    preloader.querySelector('p').textContent = `Loading timetable for ${station}...`;
    const liveboardUrl = `https://api.irail.be/liveboard/?id=${id}&format=json&lang=en`;
    fetch(liveboardUrl)
        .then((response) => response.json())
        .then((data) => {
            // we only need the departure[] containing the timetable
            const table = data.departures.departure;
            console.log('timetable', table);
            // return the transformed timetable
            return table.map((tbl) => {
                // the API sends the time in sec, we need ms
                const departure = new Date(+tbl.time * 1000).toTimeString().substring(0, 5);
                let delay = '';
                let color = 'border-green';
                // if delay is not '0', draw a red borde
                if (tbl.delay !== '0') {
                    // convert the delay from sec to min
                    delay = `+${tbl.delay / 60}`;
                    color = 'border-red';
                }
                return {
                    to: tbl.station,
                    platform: tbl.platform,
                    delay,
                    color,
                    departure,
                };
            });
        })
        .then((table) => {
            // build the timetable
            let rows = '';
            table.forEach((train) => {
                rows += `
                    <div class="${train.color}">
                      <span>${train.departure}</span>
                      <span>${train.delay}</span>
                      <span>${train.platform}</span>
                      <span>${train.to}</span>
                   </div> 
                `;
            });
            document.getElementById('timetable').innerHTML = rows;
            preloader.style.visibility = 'hidden';
        })
        .catch((error) => alert(error));
}

//This function takes in latitude and longitude of two location and returns the distance between them as the crow flies (in km)
function calcCrow(lat1, lon1, lat2, lon2) {
    const R = 6371; // km
    const dLat = ((lat2 - lat1) * Math.PI) / 180;
    const dLon = ((lon2 - lon1) * Math.PI) / 180;
    const latitude1 = (lat1 * Math.PI) / 180;
    const latitude2 = (lat2 * Math.PI) / 180;

    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.sin(dLon / 2) * Math.sin(dLon / 2) * Math.cos(latitude1) * Math.cos(latitude2);
    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
    return Math.round(R * c * 100) / 100;
}

READING TIPS

• Fetch API@Mozilla (opens new window)
• Fetch API@W3Schools (opens new window)
• Fake REST API's to test with:
  • JSON Placeholder (opens new window)
  • REQ | RES (opens new window)
  • My JSON Server (opens new window)

WATCHING TIPS

• Learn Fetch API In 6 Minutes (opens new window)