HawAPI: Explore the world of Stranger Things using this API

Summary

Show content

Introduction
What is HawAPI
- Internationalization (i18n)
- Filters
How to use the API with JavaScript
- Fetch API
- HawAPI SDK
Hawbrary
Conclusion
Resources and References

Introduction

While learning about Backend development with Java and Spring Boot I’ve decided to create a simple, but no so simpler, project. The main idea was to create an API like PokeAPI - The RESTful Pokémon APIand SWAPI - The Star Wars API.

In the time, the fourth season of Stranger Things was released and i couldn’t find a good API about the series. I had a few key features to the project:

Be Open Source
Support multi languages
A Good filter support

What is HawAPI

HawAPI is a Free and Open SourceAPI designed for Stranger ThingsTV show. It provides various information related to the show including actors, characters, episodes, games, locations and seasons through a RESTful API that allow users to access data about the series.

All this information is available through a RESTful API implemented with Java (Spring Boot) + PostgreSQL and served via JSON and allows developers to create desktop, web and mobile applications using this data very easy - HawAPI/docs

The HawAPI name comes from:

Haw: Referring to Hawkins, the fictional rural town featured in Stranger Things.
API: An abbreviation for Application Programming Interface.

Internationalization (i18n)

First of all, the support of multiple languages was the MUST-HAVE feature of the project.

The current release of HawAPI only supports English (en-US) and Portuguese (pt-BR). Soon, after release of 1.3.0, it will also support French (fr-BR) and Spanish (es-ES).

Scope	en-US	pt-BR	fr-FR	es-ES
Actors	—	—	—	—
Characters	—	—	—	—
Episodes	Yes	Yes	Soon!	Soon!
Games	Yes	Yes	Soon!	Soon!
Locations	Yes	Yes	Soon!	Soon!
Seasons	Yes	Yes	Soon!	Soon!
Soundtracks	—	—	—	—

Response examples

English

1
{
2
    "uuid": "bce28964-fcfa-4a8c-9df0-413d4648d661",
3
    "href": "/api/v1/episodes/bce28964-fcfa-4a8c-9df0-413d4648d661",
4
    "sources": [
5
        "https://www.netflix.com/title/80057281"
6
    ],
7
    "thumbnail": "https://s6.imgcdn.dev/xtSpy.jpg",
8
    "title": "The Bathtub",
9
    "description": "Eleven struggles to reach Will, while Lucas warns that \"the bad men are coming.\" Nancy and Jonathan show the police what Jonathan caught on camera.",
10
    "language": "en-US",
11
    "duration": 2580000,
12
    "season": "/api/v1/seasons/3b980ad3-aef8-4663-a7a9-64cb4979500a",
13
    "created_at": "2023-07-23T20:19:29.908",
14
    "updated_at": "2023-07-23T20:19:29.908",
15
    "episode_num": 7,
16
    "next_episode": "/api/v1/episodes/cf90565d-c906-4e2c-a992-b190b5d117f8",
17
    "prev_episode": "/api/v1/episodes/b664d023-2f2e-4d11-8af7-00d21bd565dd"
18
}

Portuguese

1
{
2
    "uuid": "bce28964-fcfa-4a8c-9df0-413d4648d661",
3
    "href": "/api/v1/episodes/bce28964-fcfa-4a8c-9df0-413d4648d661",
4
    "sources": [
5
        "https://www.netflix.com/title/80057281"
6
    ],
7
    "thumbnail": "https://s6.imgcdn.dev/xtSpy.jpg",
8
    "title": "A banheira",
9
    "description": "Onze tenta chegar a Will, mas Lucas dá o alerta de perigo. Nancy e Jonathan mostram à polícia as imagens capturadas pela câmera.",
10
    "language": "pt-BR",
11
    "duration": 2580000,
12
    "season": "/api/v1/seasons/3b980ad3-aef8-4663-a7a9-64cb4979500a",
13
    "created_at": "2023-07-23T20:19:29.908",
14
    "updated_at": "2023-07-23T20:19:29.908",
15
    "episode_num": 7,
16
    "next_episode": "/api/v1/episodes/cf90565d-c906-4e2c-a992-b190b5d117f8",
17
    "prev_episode": "/api/v1/episodes/b664d023-2f2e-4d11-8af7-00d21bd565dd"
18
}

By default English (en-US) will be used.

Filters

Second, the ability to search/filter the data from API was essential for the project, but i wanted more than a simple search endpoint.

The base of the HawAPI search:

Field	Example	Default	Options
sort	[..]?sort=first_name,ASC	—	field, ASC or DESC
page	[..]?page=1	1	1..X
size	[..]?size=12	10	1..20
language	[..]?language=en-US	en-US	I18N

Now, let’s see the complex HawAPI search where the request can be modified using the modificaton symbols.

Modification	Type(s)	Symbol
LIKE	*	*
NOT_LIKE	*	!*
BETWEEN	Number, Date	::
NOT_IN	*	!:
IN	*	:
GREATER_OR_EQUALS_TO	Number, Date	>=
LESS_OR_EQUALS_TO	Number, Date	<=
GREATER_THAN	Number, Date	>
LESS_THAN	Number, Date	<
NOT_EQUALS	*	!
EQUALS	*

With this power, we can create robust and complex API searches like:

All characters with last name like Wheeler, gender equals to 1 and birth date greater or equals to 1967-01-01
/api/v1/characters?last_name=*Wheeler&gender=1&birth_date=>=1967-01-01

How to use the API with JavaScript

In this section we’ll see how to fetch information from HawAPI using both FetchAPI and the @hawapi/js-sdkpackage:

Fetch API

Here’s how to use with the native Fetch API:

Using then/catch:

1
fetch('https://hawapi.theproject.id/api/v1/characters/')
2
  .then((response) => response.json())
3
  .then((data) => {
4
    console.log(data);
5
  })
6
  .catch((error) => console.error(error));

Using async/await:

1
async function fetchAndLogCharacters() {
2
  try {
3
    const response = await fetch(
4
      'https://hawapi.theproject.id/api/v1/characters/'
5
    );
6
    const data = await response.json();
7
    console.log(data);
8
  } catch (error) {
9
    console.error('Error:', error);
10
  }
11
}
12

13
fetchAndLogCharacters();

HawAPI SDK

We can use the HawaPI JavaScript SDK to make the code better:

Install the SDK:

npm

npm install @hawapi/js-sdk

yarn

yarn add @hawapi/js-sdk

Create the instance and Make Requests:

1
import { EpisodeModel, createClient } from '@hawapi/js-sdk';
2
// const { EpisodeModel, createClient } = require('@hawapi/js-sdk');
3

4
const client = createClient();
5

6
async function fetchAndLogCharacters() {
7
  const res = await client.getRandom<EpisodeModel>('episodes');
8
  console.log(res);
9
}
10

11
fetchAndLogCharacters();

This SDK can also be used in the browser with the <script> tag.

See more in HawAPI/js-sdk#examples/web

Hawbrary

The Hawbrary is a “library” to showcase all information provided from the HawAPI project, built with React (NextJs) + Typescript, hosted in GitHub Pages and using the official @hawapi/js-sdk.