HawAPI: Explore o mundo de Stranger Things usando essa API

Sumário

Introdução

Enquanto aprendia sobre desenvolvimento Backend com Java e Spring Boot, decidi criar um projeto simples, mas não tão simples. A ideia principal era desenvolver uma API parecida com PokeAPI - Uma API de Pokémone SWAPI - Uma API de Star Wars.

Na época, a quarta temporada de Stranger Things havia sido lançada, e eu não encontrei uma API interessante sobre a série. Defini algumas características essenciais para o projeto:

1. Ser Open Source
2. Suportar múltiplos idiomas
3. Ter um bom suporte a filtros

O que é HawAPI

HawAPI é uma API Gratuita e Open Sourceprojetada para a série Stranger Things. Ela oferece várias informações sobre a série, incluindo atores, personagens, episódios, jogos, localizações e temporadas, por meio de uma API RESTful que permite acesso a esses dados.

Todas essas informações estão disponíveis via uma API RESTful implementada com Java (Spring Boot) + PostgreSQL e servida em JSON, facilitando a criação de aplicativos desktop, web e mobile - HawAPI/docs

Internacionalização (i18n)

O suporte a múltiplos idiomas era uma característica fundamental do projeto desde o início.

A versão atual do projeto suporta apenas Inglês (en-US) e Português (pt-BR). Em breve, com o lançamento da versão 1.3.0, ela também oferecerá suporte para Francês (fr-FR) e Espanhol (es-ES).

Exemplos de respostas:

• /api/v1/episodes/bce28964-fcfa-4a8c-9df0-413d4648d661?language=en-US
• /api/v1/episodes/bce28964-fcfa-4a8c-9df0-413d4648d661?language=pt-BR

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
}

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
}

Filtros

A capacidade de realizar buscas e filtros foi essencial, mas eu queria mais do que um endpoint básico de busca.

Base da busca da HawAPI:

Exemplo avançado de busca usando símbolos de modificação:

Com esse poder, podemos criar pesquisas de API robustas e complexas como:

Todos os personagens com sobrenome parecido com Wheeler, gênero igual a 1 e data de nascimento maior ou igual a 1967-01-01

• /api/v1/characters?last_name=*Wheeler&gender=1&birth_date=>=1967-01-01

Como usar a API com JavaScript

Nesta seção, veremos como buscar informações do HawAPI usando a API Fetche o pacote @hawapi/js-sdk:

Fetch API

Veja como usar com a API nativa Fetch:

1. Usando 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));

2. Usando 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

Podemos usar o SDK do HawAPI em JavaScript para melhorar o código:

1. Instale o SDK:

npm install @hawapi/js-sdk

yarn add @hawapi/js-sdk

2. Crie a instância e faça solicitações:

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

Hawbrary

A Hawbrary é uma “biblioteca” que exibe todas as informações fornecidas pela HawAPI. Foi desenvolvida com React (NextJs) + Typescript, hospedada no GitHub Pages e utiliza o SDK oficial @hawapi/js-sdk.

⤶ ⤷

Veja a demo Hawbrarye o repositório no GitHub

Conclusão

Nesta publicação, exploramos o histórico e os recursos do projeto HawAPI, incluindo o projeto Hawbrary.

Se você achar a API útil, dê uma estrela ao repositório GitHub e aproveite o #StrangerThingsDay para criar um projeto novo!

GitHub - HawAPI/HawAPI: A Free and Open Source API for Stranger Things built with Java (Spring Boot) and PostgreSQL with support for multiple languages (i18n).

A Free and Open Source API for Stranger Things built with Java (Spring Boot) and PostgreSQL with support for multiple languages (i18n). - HawAPI/HawAPI

github.com

Recursos e Referências

• https://github.com/HawAPI/
• https://hawapi.theproject.id
  • https://hawapi.theproject.id/docs/
  • https://hawapi.theproject.id/try-it/
• https://hawbrary.theproject.id
  • https://hawbrary.theproject.id/explorer/