Introduction

In this chapter we will examine how to use a public Web API in JavaScript. We will investigate the documentation of an example API, do some experiments with it by sending example requests and examine the responses. Finally we will complete a provided starter web application with the necessary JavaScript code to make the required HTTP requests.

Because the Core track in the HYF curriculum does not cover HTML and CSS, we’ll focus solely on the JavaScript part of the application and not go into the details of the provided HTML and CSS files.

Example API: Nager.Date

This open-source, public Web API provides information about public holidays per country. Its main page can be found here: https://date.nager.at. You can enter a two-letter ISO country code (e.g., NL) and it will show the public holidays for the current year.

The API documentation can be found at this URL: https://date.nager.at/scalar/#api-version-3 .

<aside> ❗

The documentation for Web APIs varies a lot. Some APIs just provide simple README-like documentation, while others use special software to document the API and provide a playground for API experimentation. Examples of the latter are Swagger and Scalar, both based on the OpenAPI standard.

</aside>

The Nager.Date API is documented using Scalar. The API offers a number of end-points that accept GET requests. There are no endpoints for other HTTP methods, such as POST, PUT and DELETE: this API is purely for obtaining information. The one that we will be using is listed under the Public Holidays heading and is described as:

Retrieve the list of all public holidays for the specified year and country

You can get quick access to the documentation for this page at this URL:

https://date.nager.at/scalar/#api-version-3/tag/publicholiday/get/apiv3publicholidaysyearcountrycode

Here is what it looks like:

The left-hand side of the screen explains what service this particular endpoint provides, what (path and/or query) parameters it expects, and the possible response status codes.

On the right-hand side you can see the URL for this endpoint and an example of a successful response (status code 200). Below the URL, the text for a curl command that targets this endpoint is shown.If you hover your mouse over the URL a copy icon appears that allow you to copy the command to the clip board so that you can paste into a terminal window for execution.

The Test Request button brings up a pop-up window where you can enter the required parameters, for this endpoint the year and the two-letter countryCode. The ▶ Send button submits the request. The response will be shown on the right-hand side, and includes the response headers, status code and body.

<aside> ⌨️

Hands on: Give it try! Enter a year and a country code under the Path Parameters and press the Send button.

</aside>

The Test Request interface that this API conveniently provides obviates the need for reverting Postman, although of course you still can. But in that case, you would need to fill in the path parameters directly into the URL that you enter in Postman. You can copy this URL from the curl command text from the main screen, reproduced below.

https://date.nager.at/api/v3/PublicHolidays/2026/us

<aside> ⚠️

Remember that not all public Web APIs provide such convenient automated API documentation. Even those that do will not all use the same UI.

</aside>

Using JavaScript

Here is some bare-bones JavaScript code that you could use to access the endpoint discussed above:

function getRequest(url, onSuccess, onError) {
  fetch(url)
    .then((response) => {
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      return response.json();
    })
    .then((data) => {
      onSuccess(data);
    })
    .catch((error) => {
      onError(error);
    });
}

function successHandler(data) {
  console.log('Public holidays data:', data);
}

function errorHandler(error) {
  console.error('Error fetching public holidays:', error);
}

getRequest(
  '<https://date.nager.at/api/v3/PublicHolidays/2026/nl>',
  successHandler,
  errorHandler
);

It consist of the following:

function getRequest(). This function issues a GET request to the specified URL. It internally uses the native fetch() function, provided by both browsers and NodeJS, and uses JavaScript promises. JavaScript promises will be covered in the next week of the Core program. For this week, you only need to know how to use the getRequest() function, not how it works internally. The getRequest() function has the following signature:
```
getRequest(url, onSuccess, onError); 
```
where:
- url is the URL of the API endpoint for the GET request.
- onSuccess is a callback function that is called upon receipt of a successful response.
- onError is a callback function that is called if the response returned in error.
function successHandler(). This function is the implementation of the callback function to be passed as the onSuccess parameter to getRequest(). It simply logs the received JSON data to the console.
function errorHandler(). This function implements the callback function to be passed as the onError parameter to getRequest(). It logs the error to the console.

The HackYourFuture curriculum is licensed under CC BY-NC-SA 4.0 **

CC BY-NC-SA 4.0 Icons

*https://hackyourfuture.net/*

Week 9 - Networking and APIs

Introduction

Example API: Nager.Date

Using JavaScript