# 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>
 
        Copied!

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 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>
 
        Copied!

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 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>
 
        Copied!

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 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>
 
        Copied!

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 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));
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 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>
 
        Copied!

1
2

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();
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 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>
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

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'));
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# 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>

 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

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;
}
 
        Copied!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

READING TIPS

WATCHING TIPS

Learn Fetch API In 6 Minutes (opens new window)