Teachers

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, run a few experiments by sending example requests, and examine the responses. Finally, we will complete a provided starter web application with the JavaScript code needed to make the required HTTP requests.

Since the Core track does not cover HTML and CSS, we will focus only on the JavaScript.

Learning goals

Read API docs (parameters, responses)
Send test requests in Scalar
Call the same endpoint from JavaScript (fetch)

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, such as NL, and it will show the public holidays for the current year. In this API, the parameter is called countryCode and it expects values like NL or US.

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

<aside> ❗

Web API documentation varies a lot. Some APIs only provide simple README-like documentation, while others use specialized tools that document the API and provide a playground for experimentation. Examples of the latter are Swagger UI and Scalar, both based on the OpenAPI standard.

</aside>

The Nager.Date API is documented in Scalar. It provides several endpoints, and they all the GET method. There are no endpoints for other HTTP methods, such as POST, PUT, or DELETE: this API is purely for obtaining information. The one 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 allows you to copy the command to the clipboard so that you can paste it 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 a try! Enter a year and a country code under Path Parameters and press the Send button.

</aside>

The Test Request interface this API provides removes the need to use Postman, although you still can. In that case, you need to fill in the path parameters directly in the URL you enter in Postman. You can copy this URL from the curl command text on 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 you could use to access the endpoint discussed above.

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

getRequest(`https://date.nager.at/api/v3/PublicHolidays/2026/nl`, (err, data) => {
  if (err) {
    console.error("Error fetching public holidays:", err);
    return;
  }
  console.log("Public holidays data:", data);
});

The getRequest() function issues a GET request to the specified URL. We will cover using the fetch() function and JavaScript promises next week, but for now, ignore the internals of getRequest() and focus on the parameters it takes:

url: The target URL for the HTTP request
callback: This follows the error-first callback pattern: the first parameter is always the error (or null if there was no error), and the second parameter is the data.

In this example we call getRequest(), passing the URL and a callback function that runs once the request is completed. If the err parameter is truthy, the request produced an error and we log it to the console. Otherwise, we log the data.

<aside> 💡

You can find the code for a fully working web demo app in the Learning-Resources repository at the link below. You will have to clone the repository if you want to run it.

https://github.com/HackYourFuture/Learning-Resources/tree/main/core-program/week-9/public-holidays

Inspect services.js to see how the network requests are implemented.

</aside>

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

CC BY-NC-SA 4.0 Icons

*https://hackyourfuture.net/*

Found a mistake or have a suggestion? Let us know in the feedback form.

Week 9 - Networking and APIs

Introduction

Learning goals

Example API: Nager.Date

Using JavaScript