Consumir APIs REST / GraphQL

REST

En cada una de estas referencias, podremos ver que las APIs se clasifican en categorías como Animales, Anime, Conversores de divisas,… Os invito a que veáis la referencia con calma para ver que opciones encontráis, seguramente haya algo de un tema que os interese verdaderamente y siendo así, os invito a que practiquéis con ello ajeno a lo que vamos a trabajar en este apartado, que puede que el tema usado no os apasione.

• Acceso a la lista de APIs: https://shorten-up.vercel.app/9RVuGmiHhH

GraphQL

En cada una de estas referencias, podremos ver que las APIs se clasifican en categorías como APIs oficiales y APIs de solo demostración, entre otras opciones.

Como os he mencionado anteriormente, visualizar el documento con calma para ver si encontráis algo que os resulte interesante.

• Acceso a la lista de APIs: https://shorten-up.vercel.app/sls75oNuRB

Una vez disponibles estos recursos, vamos a comenzar a trabajar consumiendo una API REST desde el navegador.

Lista de personajes

Para ver la lista de personajes, lo que tenemos que hacer es introducir la siguiente URL:

http://localhost:3000/characters

Reflejándose en el acceso a los datos dentro de nuestro proyecto, que lo aplicaremos en el siguiente paso:

const dataCharacters = await fetch(`http://localhost:3000/characters`).json();

Esto sería correspondiente a la lista de todos los personajes.

Información de un personaje seleccionado

Si hacemos uso de las peticiones con un personaje concreto, usaremos la siguiente estructura para obtener esa información:

http://localhost:3000/character/<ID> 

Y los ids existentes, los tenemos desde el 1 hasta el 21 (incluido). Si seleccionamos 22 o algún valor que no esté en ese rango, nos dará un mensaje de aviso, de que no existe ese personaje seleccionado.

• Existe: http://localhost:3000/character/2

• No existe

useResource$ - Estado computacional

En el capítulo anterior hemos trabajado con la gestión de estado, que son los encargados de gestionar valores de estado común y también hemos trabajado con un valor de estado computacional, el useComputed$ que observa y devuelve inmediatamente los datos, con opción a modificarlo.

En este caso, trabajaremos con useResource$(), que tendrá un funcionamiento parecido a useComputed$ pero este hook se usará específicamente para observar los cambios de estado a la hora de obtener información remota, como es una API.

Al tener disponible la función para obtener los datos REST de la URL seleccionada, vamos al componente correspondiente a la ruta inicial (src/routes/index.tsx) y añadimos la función useResource$() de la siguiente manera:

// 1.- Importar 
import { component$, useResource$ } from '@builder.io/qwik';

export default component$(() => {
    
    // 2 Para cargar el contenido de la función que nos trae la información de la API
    const charactersListResponse = useResource$<any>(() => {

    });
    return <>
        <h1>Lista de Personajes principales de Breaking Bad</h1>
    </>
});

El resultado actual es el siguiente:

Analizándolo con más detalle, ¿En qué consiste la función useResource$()?

Este método nos va a permitir obtener los valores de una función de forma asincrónica.

Se llamará a la función asíncrona pasada como su primer argumento cuando se monte el componente y cuando cambien los valores rastreados.

Ahora vamos a trabajar dentro de useResource$(), aplicando la llamada a la API obteniendo los datos necesarios con el año actual:

// 1.- Imports necesarios
import { component$, useResource$, useStore} from '@builder.io/qwik';
import { charactersAPI } from '~/api/characters';

export default component$(() => {

    // 2
   // 2 Para cargar el contenido de la función que nos trae la información de la API
  const charactersListResponse = useResource$<any>(({ cleanup }) => {
    // 3.- Es buena práctica usar `AbortController` para abortar (cancelar) la obtención de datos si
    // llega una nueva solicitud. Creamos un nuevo `AbortController` y registramos una `limpieza` (cleanup)
    // función que se llama cuando se vuelve a ejecutar esta función.
    const controller = new AbortController();
    cleanup(() => controller.abort());
    // 4.- Llamar a la función y obtener el resultado
    return charactersAPI(controller);
  });
    return (
    <>
        <h1>Lista de Personajes principales de Breaking Bad</h1>
        <p>AQUÍ DEBEMOS DE PINTAR LA LISTA DE PERSONAJES</p>
    </>
    );
});

Y esto es lo que tenemos ahora:

El valor charactersListResponse que es el valor que se asigna desde useResource$() y tiene estos tres posibles resultados:

• pending: los datos aún no están disponibles, es decir, mientras está haciendo el proceso de obtener los datos, en estado de carga.

• resolved: los datos están disponibles.

• reject: los datos no están disponibles debido a un error o tiempo de espera superado.

Ahora ya después de usar la función useResource$() y conociendo los posibles estados de las respuesta, debemos de incrustar el componente <Resource /> que será lo que obtenemos en la vista.

Lo que vamos a añadir es la siguiente estructura:

<Resource
    value={ 
    /* VALOR ASIGNADO a la constante desde useResource$
    /* En este caso: charactersListResponse*/
    }
    onPending={() => <div>Cargando...</div>} // Mientras está ejecutando la carga
    onRejected={() => 
        <div>Fallo a la hora de cargar la lista de personajes de Breaking Bad</div>} // Rechazado
    onResolved={(result) => { 
        // Resuelto, donde renderizamos los resultados
        return <div><CONTENIDO></div>;
    }}
/>

Aplicándolo a nuestro proyecto:

// Añadir "Resource" en el import
import { component$, useResource$, useStore, Resource } from '@builder.io/qwik';
...

export default component$(() => {
    ....
    return (
    <>
        <h1>Lista de Personajes principales de Breaking Bad</h1>
        <Resource
            value={charactersListResponse}
            onPending={() => <div>Cargando...</div>} // Mientras está ejecutando la carga
            onRejected={() => (
            <div>Fallo a la hora de cargar la lista de personajes</div>
            )} // Rechazado
            onResolved={(result) => {
            return <div>{JSON.stringify(result)}</div>; 
            }}
        />
      
    </>
    );
});

Quedando de la siguiente forma, como se puede apreciar ya coge todos los datos de las carreras y lo incrusta como una cadena de texto (que por cierto, queda feo, pero podemos comprobar de una manera rápida que obtiene bien la información):

Lo que tenemos que hacer es ponerlo más organizado y más vistoso y esto lo haremos en formato lista:

<Resource
    value={charactersListResponse}
    onPending={() => <div>Cargando...</div>} // Mientras está ejecutando la carga
    onRejected={() => (
        <div>Fallo a la hora de cargar la lista de carreras</div>
    )} // Rechazado
    onResolved={(result) => {
        return result.length ? (
        <ul class="list">
            {result.map((character: any, index: number) => (
            <li key={String(character.id).concat(character.name.toLowerCase())}>
                <a href={character.url} target="_blank">
                {character.name}
                </a>{' - '}
                ({character.description}) - <Link href={`/details/${index + 1}`}>Más detalles</Link>
            </li>
            ))}
        </ul>
        ) : (
        <p>
            Sin resultados - Comprueba que la API está en funcionamiento
        </p>
        );
    }}
/>
      

El resultado será el siguiente:

Vamos a darle un mínimo de estilo, para que se pueda visualizar bien el formato lista y muestre el contenido de una manera más limpia en src/global.css:

ul {
  margin: 0% 5%;
}

h1 {
  margin: 1rem 0rem 1rem 2rem;
}

.list li::before {
  /*https://cloford.com/resources/charcodes/utf-8_misc-symbols.htm coger el valor HEX para content*/
  content: "\26B9";
  color: rgb(10, 95, 34);
  display: inline-block;
  width: 1em;
  font-weight: 800;
  margin-right: 1em;
}

ul li {
  list-style: none;
}

Quedando de la siguiente forma:

Si por lo que sea la API no responde, por ejemplo la API no está operativa por estar parada, debe de mostrarnos el siguiente estado:

Primera consulta — Lista de personajes

Consulta simple en el que usamos el resolver characters para obtener la lista de todos los personajes principales existentes, donde nos interesa obtener el id de cada uno de ellos para la segunda consulta.

Seleccionamos Query (1) para ver los resolvers disponibles, escribimos la consulta en el apartado de la mitad (2) y a la derecha su resultado (3).

Se ha especificado con lo mínimo posible para obtener el id que usaremos en la siguiente consulta junto con el nombre del personaje y votos recibidos (esto podemos prescindir si queremos).

Lo que tendríamos que tener en cuenta es lo siguiente:

• Endpoint: http://localhost:3000/graphql

• body: Dentro de la propiedad query enviamos el contenido de la consulta que sería lo que corresponde a la siguiente estructura.

{
  characters {
    id
    name
    votes
  }
}

Segunda consulta — Obtener la información del personaje seleccionado

Ahora que ya sabemos que podemos filtrar el personaje con el id que apliquemos (de 1 a 21 incluido) vamos a aplicar la siguiente consulta en el que ya estamos metiendo otro elemento, el uso de Query Variables (Variables), que son las variables que usaremos para poder hacer consultas dinámicas:

• 1: Consulta donde ya hacemos uso del filtro añadiendo los argumentos con los Query Variables (apartado Variables, depende del playground aparece de una manera u otra). Se añadirá con este contenido de la consulta:

query getSelectCharacter($id: Int!) {
  character(id: $id) {
    name
    description
    episodes
    url
    votes
  }
}

• 2: El filtro para obtener los datos mediante el uso de Query Variables. Y aquí, a continuación lo que corresponde al filtro que estamos aplicando:

{
  "id": 1
}

• 3: Resultado aplicando correctamente el filtro para obtener solo los datos cuyo id es 1.

Llegados a este punto, vemos dos maneras de realizar diferentes tipos de consultas:

• Sin uso de Query Variables
• Utilizando valores para filtrar los resultados / seleccionar elementos con más detalle.

Es importante que sepáis trabajar con la documentación de las APIs, ahí está toda la clave. Si os desenvolvéis bien, podréis trabajar consumiendo cualquier API que os encontréis por el camino y en el caso de las APIs de GraphQL, las encontraréis documentadas, por lo menos con la estructura del schema.

Con esto, terminamos este apartado y usando estos ejemplos, vamos a consumirlo con Qwik, tal y como lo hemos hecho con los endpoints correspondientes a la API REST.

Opciones de selección de personajes: detalles del personaje

Ahora ya tenemos los personajes a mano, solo nos queda generar dinámicamente los botones asociados a los personajes, para que cuando hagamos click, podamos cargar los detalles que corresponden a ese personaje, algo como lo que hemos realizado en el apartado anterior, consumiendo la API GraphQL en el navegador.

Cambiamos el código a lo siguiente:

1.- Importamos lo necesario 
import { Resource, component$, useResource$, useSignal} from '@builder.io/qwik';
import { breakingBapCharactersGraphQLAPI } from '~/api/characters';

export default component$(() => {
  // 2.- Seleccionamos 'Walter White' por defecto
  const selectCharacter = useSignal(1);
  // 3.- Accedemos a la API
  const charactersListResource = useResource$<any>(({ cleanup }) => {
    ...(Sin cambios)
  });

    // 4.- Pintamos el resultado
    return (
        <>
        <h1>Personajes Breaking Bad</h1>
        <p>Personaje seleccionado: {selectCharacter.value}</p>
        <Resource
            value={charactersListResource}
            onPending={() => <div>Cargando...</div>}
            onRejected={() => <div>Error al cargar la lista de personajes</div>}
           onResolved={({ characters }) => {
                return characters.length ? (
                <div>
                    {characters.map((character: any) => (
                    <button key={character.name.toLowerCase()}>{character.name}</button>
                    ))}
                </div>
                ) : (
                <p>Sin resultados</p>
                );
            }}
        />
        </>
    );
});

Y su resultado será el siguiente:

Añadimos la acción de click en los botones (dentro de <Resource />), para que actualice la información del continente seleccionado:

<div>
    {characters.map((character: any) => (
    <button key={character.name.toLowerCase()} onClick$={() => selectCharacter.value = character.id}>{character.name}</button>
    ))}
</div>

Por defecto, estará seleccionado el id 1 que corresponde a Walter White.

Si hacemos click en cualquiera de los otros personajes, irá cogiendo el id que le corresponde y con eso ya tendríamos lo necesario para poder cargar los detalles de cada selección.

• Jesse Pinkman

• Saul Goodman

Llegados a este punto ya tenemos el primer apartado realizado, lo que nos queda es añadir otro <Resource/> para mostrar los detalles del personaje seleccionado.

Añadimos el siguiente código para obtener la información basándonos en lo visto en la segunda consulta que hemos hecho antes que era lo siguiente (ahora está mostrando los datos de Jesse Pinkman):

Lo aplicamos al código, para que coja el valor del continente en base a nuestra selección:

import {
    component$,
    Resource,
    useResource$,
    useSignal,
} from '@builder.io/qwik';
import { breakingBapCharactersGraphQLAPI } from '~/api/characters';

export default component$(() => {
    ...
    const characterSelectResource = useResource$<any>(
    ({ track, cleanup }) => {
    // 1.- Observamos los cambios del continente seleccionado
    track(() => selectCharacter.value);
    
    const controller = new AbortController();
    cleanup(() => controller.abort());
    // 2.- Consulta para obtener los detalles del personaheje seleccionado

    return breakingBapCharactersGraphQLAPI(
        {
            query: `
              query getSelectCharacter($id: Int!) {
                character(id: $id) {
                  name
                  description
                  episodes
                  url
                  votes
                }
              }
            `,
            variables: { 
                id: selectCharacter.value
            }
        },
        controller
    );
    }
  );
    return (
        <>
    ...
        <hr />
        <Resource
            value={characterSelectResource}
            onPending={() => <div>Cargando...</div>}
            onRejected={() => <div>Falla al cargar los detalles del personaje seleccionado {selectCharacter.value}</div>}
            onResolved={() => <p>Pendiente para mostrar detalles del personaje seleccionado</p>}
        />
    </>
});

Y ahora vamos a probarlo. Al cargar hace lo siguiente (en la consola de ejecución de los eventos del servidor), siendo character los detalles correspondientes al id relacionado a Walter White:

Ahora si selecciono Jesse Pinkman, esto es lo que pasaría (en la consola del navegador).

Aquí los diferentes casos haciendo diferentes opciones:

• Saul Goodman

• Gustavo Fring

(Probad todos vosotros si tenéis curiosidad, el funcionamiento es correcto)

Pintar los resultados de los detalles en formato lista

Lo más difícil está hecho, lo que falta es reflejar esos resultados en una forma de lista (o como queramos, tampoco nos vamos a parar mucho en ello).

Añadimos dentro del código JSX debajo de los botones de selección lo siguiente:

import {
    component$,
    Resource,
    useResource$,
    useSignal,
} from '@builder.io/qwik';
import { breakingBapCharactersGraphQLAPI } from '~/api/characters';

export default component$(() => {
    ...
    return (
    <>
        ...
        <hr/>
        <Resource
            value={characterSelectResource}
            onPending={() => <div>Cargando...</div>}
            onRejected={() => <div>Falla al cargar los detalles del personaje seleccionado {selectCharacter.value}</div>}
            onResolved={({character}) => {
            return (character ?
            <ul class="list">
                {Object.keys(character).map((key: any) => (
                <li key={key.toLowerCase()}>
                    {character[key]}
                </li>
                ))}
            </ul> : <p>Sin resultados</p>
            );
            }}
        />
    </>
    );
});

Y el resultado se refleja de la siguiente forma, en este caso de manera inicial:

Seleccionando Skyler White: