I am a huge fan of Rick Riordan's books. I recently came across Apollo's Trials, based on the greek god Apollo.

When I hear any mention of Apollo, my mind goes to the greek god who was the god of practically everything – including but not limited to music, poetry, art, prophecy, truth, archery, plague, healing, sun, and light.

Apollo client, just like the god Apollo, can do many things. For example, it lets you fetch and manage data from a GraphQL API on your client-side application. It is also simple, flexible, and compatible with any data source.

In this article, we will use the Apollo client to fetch data from the Rick and Morty API, named after the animated TV show with the same name. We will write a GraphQL query to fetch the data we need. The data will then be displayed using React.

Before we get started with the project, let's go over the use cases of GraphQL, and how it differs to REST APIs.

What Are The Use Cases of GraphQL?

GraphQL is used to build applications that require real-time data synchronization, like chat applications. It allows developers to fetch necessary data, reducing data transfer over the network, and improving application performance.

Microservices handle specific functionality or feature of the application, which poses a challenge to developers to work with multiple APIs individually.

GraphQL allows developers to create a single API that acts as a gateway to numerous microservices. It also improves performance since one query retrieves various microservices in a single request.

GraphQL provides a self-documenting schema, making it easy for developers to understand the data model and relationships between data. It also eases the process of creating, testing, and maintaining API, reducing time and cost.

Finally, GraphQL provides versioning capabilities to allow the evolution of the API schema without breaking existing clients. Versioning is possible since clients specify the exact data they need, making it easy to add new fields and remove depreciated ones without affecting existing clients.

What Are The Differences Between GraphQL and REST APIs?

With GraphQL, the client sends a query with the data it needs, and the server responds with that data alone. On the other hand, with REST APIs, the client sends a request to an endpoint, and the server responds with all the data/response related to the endpoint.

REST APIs are resource-based, where the endpoints represent data that can be accessed, created, updated, or deleted. On the other hand, GraphQL is graph-based, where each node represents a relationship between objects.

REST APIs, return data in a JSON (JavaScript Object Notation) or XML (Extensible Markup Language) format. At the same time, GraphQL allows the client to specify the data they need and responds with a JSON object matching the query.

GraphQL provides versioning to enable the API's evolution without disrupting the existing clients, while REST APIs create new endpoints for each version.

In some cases, REST APIs, can suffer from over-fetching or under-fetching, where the server may send much or little data. GraphQL accounts for this by allowing clients to request the data they need, thus reducing the amount of data transferred over a network.

Project Setup

Now that you are familiar with what you can do with GraphQL, let's start building the project.

Prerequisites

• Fundamentals on React
• Know about how APIs work and CSS (Cascading Style Sheets)

Dependencies Installation

Create a new React App named "rickandmorty".

 npm init [React](https://react.dev/)-app rickandmorty

or

npx create-[React](https://react.dev/)-app rickandmorty

Install Apollo Client and GraphQL. The code below installs two dependencies:

1. @apollo/client contains everything you need, like an in-memory cache, local state management, error handling, and a React-based view layer.
2. GraphQL provides logic for parsing the queries.

npm install @apollo/client [GraphQL](https://graphql.org/)

Rick & Morty API and Apollo Client Setup

Once the project is setup, we need to start using it in our files. Next, navigate to your index.js file using the cd command, and add the following code:

import [React](https://react.dev/)DOM from '[React](https://react.dev/)-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://rickandmortyapi.com/[GraphQL](https://graphql.org/)',
  cache: new InMemoryCache(),
});

const root = [React](https://react.dev/)DOM.createRoot(document.getElementById('root'));
root.render(
  <ApolloProvider client={client}>
  <App />
</ApolloProvider>,
);

The code above creates an instance of the Apollo client with the URL (Uniform Resource Locator) of the Rick and Morty API GraphQL endpoint.

The App component is wrapped with the Apollo provider component to pass the client to all child components.

Query Implementation

Now, create a file called characters.js inside the src folder. The file will contain the query and any other functions that you want to add.

Inside the file, add the following code:

import { gql } from '@apollo/client';

export const GET_CHARACTERS = gql`
query Characters{
    characters{
      results {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
  }
`;

In the code above, we import gql from the @apollo/client to define our query.

We create and export the variable GET_CHARACTERS as a string with capitalized letters. Capitalization is considered a best practice when defining queries in GraphQL. It is also considered a best practice to wrap strings with a template literal.

Objects in Javascript are collections or containers filled with key-value pairs. A key-value pair is referred to as a property.

The query, in our case, searches for the characters in Rick and Morty. It returns an object with the results property, which is an array of character objects.

Each character has properties like name, species, status, type, gender, and image- you can choose what you want to fetch 😉.

The other properties, origin and location, are objects with a name property for each character’s origin and location.

Character Function Definition

In the character.js file, add the following code below the GET_CHARACTERS query after modifying it as shown below:

import { useQuery, gql } from '@apollo/client';
import { useState } from "[React](https://react.dev/)";
import  { RandomCharacter } from './randomcharacters';
import './App.css';

export const GET_CHARACTERS = gql`
query Characters($name: String){
    characters ( filter: {name: $name}){
      results {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
  }
`;

export function CharacterList() {
  const [searchTerm, setSearchTerm] = useState("");
  const {loading, error, data }   = useQuery(GET_CHARACTERS, {variables: {name: searchTerm}});
  const handleChange = (event) => {
    setSearchTerm(event.target.value);
  };
  return (
    <div>
      <input type="text" name="search" placeholder="search for Rick and Morty characters..." value={searchTerm} onChange={handleChange} className="search-input"  /> 
      {loading && (
            <div className="loader-container">
              <div className="loader"></div>
            </div>
       )}
      {error && <p> error </p> }
      {data?.characters.results.length === 0 && (<>   <RandomCharacter/> </>)}
      {data && data.characters.results.map((character) => (
        <div className="card" key={character.name} style={{ backgroundImage: `url(${character.image})`,backgroundRepeat: 'no-repeat'}}> 
          <div className="info"> 
          <h2 className="h3"> {character.name}</h2>
          <p> Status: {character.status}</p>
          <p> Species: {character.species} </p>
          <p> Type: {character.type}</p>
          <p> Gender: {character.gender}</p>
          <p> Origin: {character.origin.name}</p>
          <p> Location: {character.location.name}</p>
        </div>
        </div> 
      ))}
    </div> 
  );
}

The export function CharacterList() creates a function that is also exported to and can be used by other parts of the code.

The searchTerm variable initializes the search state to an empty string and creates a function setSearchTerm to update the value.

The useQuery hook from @apollo/client library fetches data from the API.

The query passes GET_CHARACTERS and a variable named searchTerm which is a variable to hold the character names being searched.

The handleChange variable sets searchTerm 's value to the input field's current value. The input field is the search bar that the user will use to search the names of the characters they want to view. The state is handled by handleChange.

We also need to account for issues with loading the site, as well as for any bugs that may occur.

loading is dynamically rendered with a spinner if loading is set to True. An error message is displayed if the error is set to True.

When the user is searching for a character that doesn't exist, we want to present a message and an alternate character they can find more information about – this is where the RandomCharacter comes in. We will define this later on. For now, let's keep it as is.

Once we fetch the data, we map the data.characters.results array to each character's card.

We also want to change the background of the cards to represent the character the information is for. The backgroundImage in the style property handles the dynamic change of the images. The rest of the items are displayed as text on the card.

How To Display Data

Now that we have a function working, we need to view what is being displayed in the browser, and whether we can make queries and get the data we need.

In your App.js file, add the following code:

function App() {
  return (
    <div>
    <h1 style={{ textAlign: 'center' }} >Rick and Morty Characters</h1>
    <CharacterList />
  </div>
      );
    }

<CharacterList /> component displays the information about the characters we are getting from the API.

How to Randomize The Characters

Remember that we called the RandomCharacter component but we have yet to define it.

Create a file called randomcharacters.js in src and add the following code:

import { useQuery } from "@apollo/client";
import { gql } from '@apollo/client';
import { useState } from "[React](https://react.dev/)";
import './App.css';

export const GET_SINGLE_CHARACTER = gql`
query Character($id: ID!){
    character   (id: $id) {
        name
        species
        status
        type
        gender
        origin{name}
        location {name}
        image
      },
    },
`;

export const RandomCharacter = () => {
    const [randomNumber, setRandomNumber] = useState(Math.floor(Math.random() * 200));
    const { loading, error, data } = useQuery(GET_SINGLE_CHARACTER, {variables: {id: randomNumber } });


  return (
    <div>
       <p className="intro" >
         Sorry, we couldn't find that character 😞  
         <br/>
         <br/>
         How about this one instead? 😉 </p>

      {/* {loading && <p>loading...</p>} */}
      {loading && (
            <div className="loader-container">
              <div className="loader"></div>
            </div>
       )}
      {error && <p> error </p> }
      {data && (<> 
        <div className="card" key={data.character.name} style={{ backgroundImage: `url(${data.character.image})`,backgroundRepeat: 'no-repeat'}}> 
        <div className="info"> 
          <h2 className="h3">{data.character.name}</h2>
          <p>Status: {data.character.status}</p>
          <p>Species: {data.character.species}</p>
          <p>Type: {data.character.type}</p>
          <p>Gender: {data.character.gender}</p>
          <p>Origin: {data.character.origin.name}</p>
          <p>Location: {data.character.location.name}</p>
        </div>
        </div>
      </>
      )}
    </div>
  );
};

We will replicate the query we created in the characters.js file, and rename it to GET_SINGLE_CHARACTER. Instead of looking for names, we will look for IDs.

We look for IDs because they are unique, and we want to randomize the characters that will be picked once a user does not get the character they are looking for.

randomNumber initializes state to the Math.floor function which generates a random number between 0 and 199 inclusive, using the Math.random() method and multiplying it by 200.

The Math.floor function rounds the result of the expression to the nearest integer. Every time the randomNumber needs to be updated the setRandomNumber function takes a new value as its argument and updates the state.

We have a message to alert the user that the character they are looking for is not found, but they can check out a new character.

The loading spinner is also implemented in this component, and the errors are there in case any issues occur. The images and cards are similar to the characters.js format since we want consistency with how everything looks.

How to Style the Display

We will use CSS to style how the cards will look, along with the search bar and the general page.

Having defined the functions and components, we will be adding className attributes to what needs to be styled.

Add the following code:

@import url(https://fonts.googleapis.com/css?family=Roboto:400,500,700);
body{
  background: navajowhite;
  font-family: Roboto, veranda;
  padding-bottom: 4em;
}
.card{
  position: relative;
  width: 22em;
  height: 30em;
  background-size: 22em 30em;
  box-shadow: 3px 3px 20px rgba(0,0,0,0.5);
  margin: auto;
  overflow: hidden;
  margin-bottom: 2em;
}
.card *{
  position: relative;
  z-index: 2;
}
.card:hover .info{
  bottom: -3em;
  opacity: 1;
  padding: 2px 1px;
  background-color: navajowhite;
}
.info{
  font-family: 'Droid Serif', serif;
  font-size: 1.2em;
  color: black;

  line-height: 1.1em;
  padding: 0 2em;
  position: relative;
  bottom: -4em;
  opacity: 0;
  background: transparent;
  transition: opacity 0.3s, bottom 0.3s;
  text-align: center;
}
/* search  bar*/
input[type="text"] {
  border: none;
  border-radius: 10px;
  background-color: #f2f2f2;
  padding: 10px;
  width: 500px;
  margin: 0 auto;
  display: block;
  font-size: 16px;
  font-family: 'Roboto', sans-serif;
  box-shadow: 2px 2px 5px rgba(0,0,0,0.2);
  margin-bottom: 2em;
}

input[type="text"]::placeholder {
  color: #999;
  font-style: italic;
}
/* no result */
.intro{
/* width: 10px; */
text-align: center;
margin: 0 auto;
color:black;
font-family: 'Droid Serif', serif;
font-size: 23px;
font-style: italic;
line-height: 20px;
padding-bottom: 15px;
}
/* spinner */
.loader-container {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100px;
}

.loader {
  border: 8px solid #f3f3f3; 
  border-top: 8px solid black;
  border-radius: 50%;
  width: 50px;
  height: 50px;
  animation: spin 1s linear infinite;
}

@keyframes spin {
  0% { transform: rotate(0deg); }
  100% { transform: rotate(360deg); }
}

Things to note:

• The class .card represents what the card will look like.
• The class .info represents the body text for the characters, such as the species.
• The class .intro represents the text that appears if the character is not found.
• The class .loader represents the spinner that shows before the results are displayed.

Your website should now look like this.

Conclusion

In this article, you learned how to use GraphQL queries with React, manage state using the useState hook, and style the different components of the web application.

May your keyboard be swift, your bugs be few, and your fun meter be off the charts as you code away!

My strengths were swimming and basketball. I went home with many gifts or, as my school's game master said, a token of appreciation.

A token is a secure form used to transmit data between two parties. The medals I got from the competitions hold a lot of value for me, and if I gave them to someone else, they would merely be trinkets.

JavaScript Object Notation (JSON) is a format used to present structured data based on JavaScript syntax. We use it to transmit data in web applications by sending the data from the server to the client's display.

JWT (JSON Web Token) is a form of transmitting a JSON object as information between parties. Let's learn more about what JWTs are and how they work.

The Importance of JWTs

JWTs are important for two main reasons:

Authorization: in our competitions, we had to present our school identification cards for verification before getting our medals.

Our school IDs acted like log in requests in applications. These requests, in apps, contain a JWT that allows users to get permission to access any resources that are accessible with that token.

Information exchange: my medals were a badge of honor and a way to get a certificate signed and stamped by our games master for legitimacy.

We use JWTs to exchange information in cases where they are signed – for example using public-private key pairs to make sure that the integrity of the information is not compromised since the payload and header are used to compute signatures.

How Do JWTs Work?

A JWT is an authorization token that is included in requests. Here's an example of what one looks like:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjczNTI3ODMzLCJpYXQiOjE2NzM1Mjc0MzAsImp0aSI6IjNkMGRkMGZiZjA5ZjRmZWU4MTZmMGQyOTQ5OWU3ZmFmIiwidXNlcl9pZCI6IjFmYTBiMGJkLWY4MmMtNDQzNy1iMmViLTMwOTYzMGZkNzQ2NiJ9.-swqFh4MCecycmodQfO8ZmfsDJ3DqoZBsdNzEWhfzhA

You can get a JWT through logging in with a username and password. In exchange the server returns an access and refresh token in the form of a JWT. The tokens access resources on the server.

The lifetimes of the access and refresh tokens vary since access tokens last for five minutes or less while the refresh tokens can last for 24 hours. But you can customize the timelines of both types of tokens.

If the access token expires, the client uses the refresh token to summon a new access token from the server. Once the refresh token expires, the user must log in again with their username and password to get a new pair of tokens.

It works this way to prevent damage that can occur when a token is compromised and to prevent unauthorized access.

Different parts of a JWT

JWTs hold information in three parts, as you can see in the following code blocks:

header.payload.signature

header = eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9F5
payload = eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNTQzODI4NDMxLCJqdGkiOiI3ZjU5OTdiNzE1MGQ0NjU3OWRjMmI0OTE2NzA5N2U3YiIsInVsztZXJfaWQiOjF9
signature = Ju70kdcaHKn1Qaz8H42zrOYk0Jx9kIciuhkTn9Xx7vhikY

The above JWT is encoded using Base64. Once decoded, the information will include something similar to the following parts:

Header

The header contains:

• type: the specification that the token is a JWT
• algorithm: the signing algorithm used to sign said token

Algorithms that are used to sign include RSA, HMAC, or SHA256. The signatures for the tokens serve two purposes – integrity and authenticity.

An example of a header with the algorithm and type is as shown below:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

The payload contains the intended messages which are commonly known as claims and metadata, as well as any other information.

There are three types of claims:

1. Registered claims: they include exp (expiration time), iss (issuer), sub (subject) and aud (audience). They are highly recommended since they provide information on the use and condition of use of the token.
2. Public claims: these are claims that are unique to avoid collisions with other services that use JWT.
3. Private claims: these are claims that are used specifically between two parties that understand the meaning and use. Like the example of my medals, my games master and I understood the value.

Below is an example of what a payload looks like.

{
  "token_type": "access",
  "exp": 1543828431,
  "jti": "7f5997b7150d46579dc2b49167097e7b",
  "user_id": 4
}

• token_type is a label that shows what kind of token this is. Case in point, it's an access token.
• exp stands for expiration. It's the time the token will stop working – in this case the number represents date and time in Unix time.
• jti stands for JWT ID. It's a unique identifier for this specific token. The ID is used to keep track of which tokens have been used, to prevent use of the same token more than once.
• user_id: is an identifier of the user this token belongs to. In this case, the number 4 is the user identification.

Signature

The signature verifies that information is only accessed by authorized people. It is issued by the JWT backend using base64 + payload +SECRET_KEY.

The signature is verified for each request. To validate the signature, you use the SECRET_KEY. Remember the purpose of having it called SECRET_KEY is so that it is secret.

Now let's see how JWTs work in practice with an example.

Project Setup

To illustrate how JWTs work, I will use the simple JWT, which is a JSON Web Token authentication plugin for Django Rest Framework (DRF).

Prerequisites

To follow along, you should have some prior knowledge of HTML files and how to set up a Django project. You should also be familiar with what an API (Application Programming Interface) is.

You will also need to have a Django project already setup. You could name it tokenization also add an app called access.

Once your app and project are set up, you are good to go.

Simple JWT Installation

As mentioned, I will be using the simple JWT which provides JWT authentication for the Django Rest Framework (DRF).

DRF is a third-party package for Django used as a toolkit for building Web API's. It provides a seamless experience while you build, test, debug and maintain RESTful APIs using in Django.

RESTful APIs (Representational State Transfer APIs) are a type of web API that allow communication between different applications over the internet in a fast, reliable, and scalable way.

RESTful APIs are stateless. This means that requests contain information to finalize the request, and the server does not need to remember the history of previous requests.

To install simple JWT, use the command below in your terminal:

pip install djangorestframework_simplejwt

How to Set Authentication to Simple JWT

Go to your project (tokenization), and in the settings.py file, add the following code to configure the REST framework to use simple JWT for authentication:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

The code above specifies the default authentication class to be used for all API views in the application.

DEFAULT_AUTHENTICATION_CLASSES': [ 'rest_framework_simplejwt.authentication.JWTAuthentication', ] sets the default authentication class to be JWTAuthentication from the rest_framework_simplejwt package. This means that all API views in the project will use JWT authentication by default.

How to Define Uniform Resource Locator Patterns

In your project (tokenization), create a file (if you have not created one yet) named
urls.py . Then add the following code:

from django.urls import path
from rest_framework_simplejwt import views as jwt_views

urlpatterns = [
    path('api/token/', jwt_views.TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', jwt_views.TokenRefreshView.as_view(), name='token_refresh'),
]

The path function creates a new URL pattern and maps it to the specified view.

The URL (Uniform Resource Locator) path /api/token/ is mapped to the view jwt_views.TokenObtainPairView.as_view(). The as_view()method converts the class-based view to a function-based view used in routing. The name parameter makes it easy to refer to the URL pattern in other parts of your code.

We have now created an endpoint for obtaining JWT tokens. If a request is made to the endpoint, TokenObtainPairView, view handles the request and returns a JWT token in the response for authentication.

How to Customize the Token Timelines

To customize the timeline of the tokens, first add the rest_framework_simplejwt in your installed apps section in the project (tokenization) under the settings.py file. The purpose for adding the rest_framework_simplejwt is for configuration.

To add the timeline we want, we will first create a dictionary called SIMPLE_JWT. Then we'll create variables to hold timelines for the access and refresh token.

The code snippet below shows how to set up the timelines for the tokens:

INSTALLED_APPS = [
    #other files
    'rest_framework_simplejwt',
]

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=5),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}

Before you use the timedelta you will need to import it like this: python from datetime import timedelta.

Visual Interaction of the API

In this section, we will use the Django Rest Framework web interface to access the endpoints.

Testing tokenization

The access and refresh tokens are highlighted in red, as shown above. To get the tokens for a user, you need to input the correct password and username for an existing user.

Use a refresh token through this endpoint for an access token: /api/token/refresh/

Refresh token

A refresh token gets an access token without the user using their login credentials to extend the user's session. This provides a seamless user experience and improves security by reducing the number of times a user has to key in their credentials.

How to Add a Homepage

If you want to create a visually appealing interface, you can build a custom homepage to replace the current display of the API endpoints and error messages.

To add a homepage to your Django project, follow these steps:

1. Create a templates folder in your application (access). Then, add a index.html file inside.
2. Create a static folder in your application (access) and add a img folder inside.
3. In this case, I wanted to display an image, so I added the me.png in the img folder.
4. Add the code below to your html file:

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <title>Home</title>
    <style>
        body {
            background-image: url("{% static 'img/me.png' %}");
            background-size: cover;
        }
    </style>
</head>
</html>

You will notice that we needed to add {% load static %} at the top of the file for proper styling and functioning of the site. {% load static %} serves files like stylesheets(CSS), scripts(JS), and images to your HTML templates to provide the user with a seamless experience while viewing your site.

How to Define the URL Patterns For Your Home Page

In your app's (access) urls.py file (create one if you do not have it) add this:

from django.urls import path
from django.views.generic import TemplateView

app_name='access'

urlpatterns=[
path('', TemplateView.as_view(template_name='home.html'), name='home'),

]

In your project's (tokenization) settings.py file, add the following code so that the static files are served:

# Static files settings
STATIC_ROOT = os.path.join(BASE_DIR, 'static')
STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'access/static')]

Once you run the server, your home page should be like this:

home page

Bugs and Solutions

At some point, I may have deleted the migrations file which deleted some of the data I had. This caused the following error django.db.utils.OperationalError: no such table: customUser.

I was able to solve this through running the command python manage.py migrate --run-syncdb . The command syncs tables by looking into tables not created and then creating them.

I also had an issue of using a port that was already being used by a program I had left running and forgotten about.

To close a port you should identify the process using it by running the command lsof -i :<port_number>. This will show you the user using it and PID. To stop the process use kill <PID>. Additionally, you can use sudo kill -9 -u <username> <pid> .

It's good to know that to kill the port you will need administrator permissions. Also, stopping a process can cause data loss or unusual behavior so ensure your data is backed up before doing this.

Wrapping Up

In this tutorial, you have learned how JWTs work, the structure of different tokens, how to use JWT and DRF to get tokens, how to create and serve static files in Django, and how to handle deleting migration files and kill a port.

There is so much you can learn about Django and the Django Rest Framework.

The code for this article can be found here.

May your keyboard be swift, your bugs be few, and your fun meter be off the charts as you code away!

Thanks for reading my article on how to implement tokenization using JWT and Django Rest Framework. I'm always up for a good chat about coding and tech, so give me a follow on Twitter and let's continue the conversation there.