Forem: StepZen

How to Build Angular Search Functionality with GraphQL?

Roy Derks — Mon, 27 Mar 2023 12:46:11 +0000

In this tutorial, you will learn how to build a fullstack Angular application that uses GraphQL to fetch data from a server. The application we'll build together will display a list of blog posts fetched from a GraphQL API using Apollo Client, including search functionality. To create the GraphQL API, we will use StepZen, a GraphQL API platform that allows you to build and deploy a GraphQL API in minutes.

Do you prefer watching a video walkthrough instead? Check out the link below:

Introduction

Google has developed Angular, an open-source web application framework based on TypeScript. The initial release of Angular from angular.js involved a complete rewrite, enabling the creation of large-scale, cross-platform applications.

Angular has gained a reputation for its exceptional developer tooling, which includes built-in features such as TypeScript support, routing, and a command-line interface. Additionally, Angular's component-based architecture, remarkable speed and performance, and other powerful features make it a popular choice among developers.

Prerequisites

To follow this tutorial, you will need the following:

Node.js installed on your machine
Angular CLI installed on your machine (you can install it globally by running the following command using npm: npm install -g @angular/cli)
StepZen CLI installed on your machine (you can install it globally by running the following command using npm: npm install -g stepzen)

You can find the source code for this tutorial on GitHub.

Setting up a new Angular project

To build an Angular application, we will use the Angular CLI. The Angular CLI is a command-line interface that allows you to create, build, and test Angular applications.

If you don't have the Angular CLI already on your machine, you can install it globally by running the following command using npm:

`npm install -g @angular/cli`

Note: The Angular CLI requires a minimum Node.js version of either v14.20, v16.13, or v18.10. With the Angular CLI installed, we can now create a new Angular application by running the following command:

`ng new with-angular --directory ./with-angular`

This command will create a new Angular application named with-angular, and we specified the directory where the application will be created with the'-- directory' flag. The Angular CLI will create a new directory named with-angular if it doesn't exist and will create the application inside the directory.

After the Angular CLI has finished creating the application, we can now navigate to the application directory and start the development server by running the following commands:

cd with-angular
ng serve --open

The ng serve command will start the development server, and the --open flag will open the application in the default browser.

With the starter application running, we can now start building our application. But before we can start building the application, we need to create a GraphQL API that we can use to fetch data. In the next section, we'll create a GraphQL API using StepZen.

Creating a GraphQL API with StepZen

The Angular application we build in this blog post will fetch data from a GraphQL API. To create a GraphQL API, we will use StepZen, a GraphQL API platform that allows you to build and deploy a GraphQL API in minutes. One of the capabilities of StepZen is transforming REST APIs into GraphQL APIs, which will be demonstrated in this tutorial.

Before creating a GraphQL API, we need to create a StepZen account. You can create a free account by visiting the StepZen website. And once you've created an account, you can install the StepZen CLI (if you haven't already) by running the following command:

`npm install -g stepzen`

With the StepZen CLI installed, we can now create a new StepZen project in the with-angular directory by running the following command:

mkdir stepzen
stepzen init --endpoint=api/with-angular

The blog posts we want to show in our application are fetched from the DEV.to API. More specifically, we will fetch the posts from the DEV.to API's articles endpoint: https://dev.to/api/articles?username=gethackteam. The articles endpoint returns a list of articles, and you could provide a different username to fetch articles from another user.

To create a GraphQL API that fetches data from the DEV.to API, we can use the import command from the StepZen CLI. This command will create a GraphQL schema for this REST API:

`stepzen import curl 'https://dev.to/api/articles?username=gethackteam' --name=posts --query-type=Posts --query-name=posts`

Which generates a new GraphQL schema in a directory named posts, which has a query called posts that returns a list of posts. The --query-type flag specifies the name of the type that the query will return, and the --query-name flag specifies the query's name.

From a different DEV.to endpoint, we want to retrieve a single post by its ID to retrieve a list of posts. To do this, we can use the import command again, but this time we'll use the --query-type and --query-name flags with different values to specify the name of the type and query:

`stepzen import curl 'https://dev.to/api/articles/1366695' --name=post --query-type=Post --query-name=post`

There might be some overlap between type names when importing multiple REST APIs using stepzen import curl. The StepZen CLI will notify you of this, and you can manually delete the duplicated types from the GraphQL schemas. For this project, we can delete the User, and Organization types from the file post/index.graphql as these were already specified in the schema for the first import.

To deploy the GraphQL API, we can run the following command:

`stepzen start`

This command will deploy the GraphQL API to the StepZen cloud. Once the GraphQL API is deployed, you explore the GraphQL API from the Explorer in the StepZen dashboard by visiting the following URL: https://dashboard.stepzen.com/explorer?endpoint=api%2Fwith-angular%2F__graphql.

From the Explorer, you can run queries and mutations against the GraphQL API. For example, you can run the following query to retrieve a list of posts:

query GetPosts {
  posts {
    id
    title
    description
  }
}

You can also search for articles from a specific user by changing the username parameter in the query, as shown in the screenshot below.

With the GraphQL API deployed, we can now start building our Angular application. In the next section, we'll add Apollo Client to our Angular application.

Adding Apollo Client to our Angular application

Install Apollo Client for Angular

`ng add apollo-angular`

We're using the Angular CLI to add the library apollo-angular rather than npm, as this will autogenerate some of the boilerplate code to set up Apollo Client. The Angular CLI will prompt you for the endpoint of your GraphQL API, which you can answer with the endpoint of your GraphQL API that you deployed in the previous step. The endpoint of your GraphQL API is printed in the terminal after running stepzen start, and will look something like this: https://YOUR_USERNAME.stepzen.com/with-angular/__graphql.

Once entering your GraphQL API endpoint and the GraphQL version (you can use the suggested one), the Angular CLI will generate the setup files for Apollo Client and reference it in the entry point of your application:

CREATE src/app/graphql.module.ts (713 bytes)
UPDATE package.json (1128 bytes)
UPDATE tsconfig.json (895 bytes)
UPDATE src/app/app.module.ts (462 bytes)

These steps complete the installation of Apollo Client but don't handle the data fetching part yet. The next section will add a new Angular component and fetch data from the GraphQL API.

Fetching data with Apollo Client

The query we'll use to display the blog posts is the same one we created in the first part of this blog post. You need to create a new file called graphql.operations.ts in the app directory and add the following content:

import { gql } from 'apollo-angular'

const GET_POSTS = gql`
    query GetPosts {
        posts {
        id
        title
        description
        }
    }
`

export { GET_POSTS }

And use the Angular CLI to generate the boilerplate files for a new component called posts in the app directory:

`ng generate component posts --module app`

The Angular CLI will create a new directory called posts with the files for the business logic (*.ts), styling (*.css), markup (*.html), and testing (*.spec.ts).

To add the logic to fetch the data from the GraphQL API, you can replace the code in posts/posts.component.ts with the following:

import { Component, OnInit } from '@angular/core';
import { Apollo } from 'apollo-angular';
import { GET_POSTS } from '../graphql.operations';

@Component({
  selector: 'app-posts',
  templateUrl: './posts.component.html',
  styleUrls: ['./posts.component.css']
})

export class PostsComponent implements OnInit {
  posts: any[] = [];
  error: any;
  constructor(private apollo: Apollo) { }
  ngOnInit(): void {
    this.apollo.watchQuery({
      query: GET_POSTS
    }).valueChanges.subscribe(({ data, error }: any) => {
      this.posts = data.posts;
      this.error = error;
    }
    );
  }
}

But we also need to add the styling and markup to render the posts in the application. In posts.component.html and posts.component.css, let's add the following HTML and CSS:

Add the following HTML code in posts.component.html:

<div class="main">
    <div *ngIf="error">
        <p>Error: {{ error }}</p>
    </div>
    <div class="posts-container" *ngIf="posts">
        <ul>
            <li *ngFor= "let post of posts">
                <div class="post">
                    <span class="post-title">{{ post.title }}</span>
                    <span class="post-description">{{ post.description }}</span>
                </div>
            </li>
        </ul>
    </div>
</div>

And the following CSS in posts.component.css:

.main {
    margin-top: 60px;
}
.posts-container ul {
    list-style: none;
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    grid-gap: 10px;
}
.posts-container ul li {
    padding: 10px;
    border-bottom: 1px solid #e0e0e0;
}
.post {
    display: flex;
    flex-direction: column;
    padding: 10px;
}
.post-title {
    font-size: 18px;
    font-weight: bold;
    padding-bottom: 10px;
}
.post-description {
    font-size: 14px;
}

To render the posts in the application, we need to add app-posts (the selector from PostsComponent) to the app.component.html file. In this file, replace the content with the following:

<header role="banner">
  <img src="https://stepzen.comdata:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTAgMjUwIj4KICAgIDxwYXRoIGZpbGw9IiNERDAwMzEiIGQ9Ik0xMjUgMzBMMzEuOSA2My4ybDE0LjIgMTIzLjFMMTI1IDIzMGw3OC45LTQzLjcgMTQuMi0xMjMuMXoiIC8+CiAgICA8cGF0aCBmaWxsPSIjQzMwMDJGIiBkPSJNMTI1IDMwdjIyLjItLjFWMjMwbDc4LjktNDMuNyAxNC4yLTEyMy4xTDEyNSAzMHoiIC8+CiAgICA8cGF0aCAgZmlsbD0iI0ZGRkZGRiIgZD0iTTEyNSA1Mi4xTDY2LjggMTgyLjZoMjEuN2wxMS43LTI5LjJoNDkuNGwxMS43IDI5LjJIMTgzTDEyNSA1Mi4xem0xNyA4My4zaC0zNGwxNy00MC45IDE3IDQwLjl6IiAvPgogIDwvc3ZnPg==" />
  <span>My posts</span>
</header>

<app-posts></app-posts>

Finally, add styling to the app.component.css file:

* {
    font-family: Arial, Helvetica, sans-serif;
    padding: 0;
}
header {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    height: 60px;
    display: flex;
    align-items: center;
    background-color: #1976d2;
    color: white;
    font-weight: 600;
}
header img {
    margin: 0 16px;
}

The application should now look like this; make sure to run npm start to start the development server:

But that's not all. You can also search posts by username. In the next section, we'll extend the functionality of this application by adding a search bar.

Adding search functionality

In this section, we'll add a search bar to the application to search for posts by username. With this functionality, we can search for posts by a specific user.

For starters, we will add a new query to the graphql.operations.ts file. This query will take a username as an argument and return the same fields as the GET_POSTS query:

// ...
const GET_POSTS_BY_USERNAME = gql`
    query GetPostsByUsername($username: String!) {
        posts(username: $username) {
            id
            title
            description
        }
  }
`

export { GET_POSTS, GET_POSTS_BY_USERNAME }

From the file posts/posts.component.ts, we first need to import the built-in forms library @angular/forms and the GET_POSTS_BY_USERNAME query:

import { Component, OnInit } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';
import { Apollo } from 'apollo-angular';
import { GET_POSTS, GET_POSTS_BY_USERNAME } from '../graphql.operations';
// ...

In the same file, we will add a new method called searchPosts that will be called when the user submits the search form. This method will take the GET_POSTS_BY_USERNAME query and pass the username as an argument. The data for posts will be overwritten with the new data:

// ...
export class PostsComponent implements OnInit {
  posts: any[] = [];
  error: any;
  searchForm = new FormGroup({
    username: new FormControl('gethackteam', Validators.required),
  });
  searchPosts() {
    this.apollo.query({
      query: GET_POSTS_BY_USERNAME,
      variables: {
        username: this.searchForm.value.username,
      }
    }).subscribe(({ data }: any) => {
      this.posts = data.posts;
    });
  }

To add the search bar, we will add a form element to the markup file posts.component.html:

<div class="main">
    <div *ngIf="error">
        <p>Error: {{ error }}</p>
    </div>
    <form class="form" [formGroup]="searchForm" (ngSubmit)="searchPosts()">
        <input class="input" type="text" name="username" placeholder="Enter username" formControlName="username" />
        <br />
        <button class="submit-button" [disabled]="searchForm.invalid">SUBMIT</button>
    </form>
    <!-- ... -->

And to complete the search functionality, you can add the following styling rules to the bottom of the file posts.component.css:

form {
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 10px;
}
form input[type="text"] {
    padding: 5px 10px;
    margin-right: 10px;
}
form button {
    padding: 7px 12px;
    border: 0px;
    border-radius: 3px;
    background: #E23237;
    color: #FFF;
}

If you go to the Angular application running in your browser on localhost you can now search by username. A placeholder username is already present, and you can press the "submit" button to search for posts written by this username. Or, replace this value with your own username.

Congrats on building a fullstack Angular application! The final application should look something like the screenshot above. You can add features like error and loading status or routing to display an individual post to continue learning.

Conclusion

This tutorial taught you to use GraphQL in an Angular application using Apollo Client. With Angular, you can build scalable frontend applications with native TypeScript support. On the other hand, Apollo Client is a library to help you fetish data from a GraphQL API. For example, the GraphQL API you created in this tutorial by transforming the DEV.to REST API into GraphQL using StepZen.

Head over to our examples repository for more examples of using GraphQL and frontend libraries. Or the StepZen docs to learn more about building GraphQL APIs? If you have questions about this tutorial, you can ask for help on our Discord channel.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Building a JWT Login Flow with Auth0, Next.js, and StepZen

Roy Derks — Wed, 15 Feb 2023 13:34:42 +0000

Almost every frontend application needs some form of authentication. This post will build a JWT login flow with Auth0, Next.js, and StepZen. Auth0 Next.js authentication library nextjs-auth0, a library maintained by Auth0 to make integrating with Next.js flawless, will handle the authentication flow. Auth0 is a popular authentication provider that supports many different authentication methods, including social login, passwordless login, and more.

TLDR; You can find the complete source code for this blog post on GitHub.

What does the login flow look like?

For this login flow, we will rely on OAuth 2.0 and more specifically the Authorization Code Grant flow. This flow involves both a frontend and a backend. The frontend application will handle the login flow and redirect the user to the backend. The backend will exchange the authorization code for a JSON Web Token (JWT) and return it to the frontend application. The frontend application will then use the JWT to make requests to the backend.

The frontend application will be a Next.js application that uses the nextjs-auth0 library to handle the login flow. In this application, users click a button that brings them to the Auth0 Universal Login page. From this page, they can log in using a combination of email address and password, or one of the many social providers that are available in Auth0. After logging in, the user is asked to grant access to their profile information to the authorization server. The backend StepZen GraphQL API references an Auth0 JSON Web Key Set to verify the JWT before returning sensitive data to the frontend application.

Setting up Auth0

In this section, we will configure our Auth0 account to integrate it into our application later. This involves creating an Auth0 account, creating an API in the Auth0 dashboard, and an application that will be used to generate access tokens for our StepZen GraphQL API.

First, you need to have an Auth0 account. If you don't have one yet, you can create one for free by following the instructions on the Auth0 website.

Second, we need to create an API in Auth0. This API will represent our StepZen GraphQL API and give it access to the Auth0 authorization server. To do this, we need to go to the Auth0 dashboard and:

Click the Applications link in the left navigation pane.
Click the APIs` link in the left navigation pane.
Click the + Create API button.
On this page you need to fill out the following fields:
- Enter a name in the Name field to help you identify this client. For example: "My StepZen API".
- For the Identifier field, enter a unique value. For example: "https://my-stepzen-api.com".
And click the Create button.

You should now see a page that contains the Identifier and Audience fields. The Identifier is the URL that will be used to identify your API; this is the value that will be used to identify your API when requesting an access token. We will need these values later on, so copy them somewhere.

Not setting up an API in this stage will lead to Auth0 creating an opaque access token. This token will not be able to be validated by StepZen, but only by Auth0. This is not what we want, so make sure to create an API.

Finally, we need to create an application in Auth0. This application is the authorization server that will be used to generate access tokens for our StepZen GraphQL API.

Go Back to the Applications page.
Click the + Create Application button.
Fill out the following fields:
- Enter a name in the Name field to help you identify this client. For example: "My StepZen App".
- For application type, select Single Page Web Applications (or Regular Web Applications).
Click the Create button.

Go the Settings tab to find the configuration needed to integrate with StepZen:

Domain
Client ID
Client Secret

Copy the values for the Domain, Client ID, and Client Secret fields. We will need these values in our frontend application later on.

We also need to configure the application to allow it to redirect to our frontend application. Scroll down to the Allowed Callback URLs field and add the following URL: "http://localhost:3000/api/auth/callback"

Great! We have now configured our Auth0 account and can move on to the next step.

Creating a Next.js application

In this section, we will create a Nextjs frontend application to handle the login flow with nextjs-auth0. This application will use the nextjs-auth0 library to handle the login flow. This library will take the redirect to the Auth0 Universal Login page and handle the callback from the Auth0 authorization server. It will also handle storing the JWT in the browser and, optionally, refreshing the JWT when it expires.

You can create a new Nextjs application by running the following command:

bashnpx create-next-app`

The Next.js setup will prompt you with a few questions, such as the name you want to give to the application, if you want to use TypeScript, and if you want to use experimental features. We will use the default settings for this post, so you can press enter to accept the default values.

Once you've finished the setup of the Next.js application, let's install the following dependency that is needed for authentication:

`bash
npm install @auth0/nextjs-auth0

or if you're using yarn

yarn add @auth0/nextjs-auth0
`

And add your Auth0 API and Application configuration to the .env file:

bash AUTH0_SECRET='LONG_RANDOM_VALUE' # A long, secret value used to encrypt the session cookie AUTH0_BASE_URL='http://localhost:3000' AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0.com' AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID' AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_ID' AUTH0_AUDIENCE='YOUR_AUTH0_API_IDENTIFIER'

You can execute the following command to generate a suitable string for the AUTH0_SECRET value: node -e "console.log(crypto.randomBytes(32).toString('hex'))"

With the configuration in place, we can now add the code to the Next.js application to use the nextjs-auth0 library to handle the login flow.

Create a new file called pages/api/auth/[...auth0].ts (or create the file as .js if you prefer not to use TypeScript). The nextjs-auth0 library will use this file to handle the login flow and as the callback URL for the Auth0 authorization server.
Add the following code to the new pages/api/auth/[...auth0].ts file:

`ts
import { handleAuth, handleLogin } from '@auth0/nextjs-auth0';

export default handleAuth({
login: handleLogin({
authorizationParams: {
audience: process.env.AUTH0_AUDIENCE, // or AUTH0_IDENTIFIER
// Add the offline_access scope to also get a Refresh Token
scope: 'openid profile email', // or AUTH0_SCOPE
},
}),
});
`

We also need to wrap the application with the UserProvider component. This component will be used to store the user information in the React context. This will allow us to access the user information in any component in the application. For example, by using any of the Hooks provided by nextjs-auth0. To do this, we need to add the following code to the pages/_app.tsx file:

`ts
// pages/_app.tsx
import '@/styles/globals.css';
import type { AppProps } from 'next/app';
import { UserProvider } from '@auth0/nextjs-auth0/client';

export default function App({ Component, pageProps }: AppProps) {
return (

);
}
`

The last step is to add a login button to the application. To do this, we need to add the replace the contents in the pages/index.tsx file with the following code:

`tsx
// pages/index.tsx
import Head from 'next/head';
import Link from 'next/link';
import styles from '@/styles/Home.module.css';

export default function Home() {
return (
<>

My StepZen App

  <main className={styles.main}>
    <Link href='/api/auth/login' className={styles.loginButton}>
      <span className={styles.auth0Logo} />Login with Auth0
    </Link>
  </main>
</>

);
}
`

And finally, we need to add some styles to the application. Open the file called styles/Home.module.css and add the following code to the bottom of it:

`css
.loginButton {
display: flex;
align-items: center;
background: #eb5424;
padding: 10px 20px;
border-radius: 10px;
font-size: larger;
color: white;
}

.auth0Logo {
width: 32px;
height: 32px;
margin-right: 10px;
background: url('/auth0_icon.svg');
}
`

Now run the application by executing the following command:

`bash
npm run dev

or if you're using yarn

yarn dev
`

Open the application in your browser by navigating to http://localhost:3000. You should see a login button:

Once you press the login button, you should be redirected to the Auth0 Universal Login page. Sign up here for a new account that will be added to the linked Auth0 account.

After clicking the Continue button, you should be redirected back to the application. If you open the browser's developer tools and look at the cookies, you should see a new cookie added that includes your JWT. This cookie is used to authenticate you in the application.

We now have the first part of the login flow that uses Auth0 to get a JWT. Next, we want to use this JWT to authenticate the user in the StepZen GraphQL API, so we can fetch the user's profile information from the Auth0 API.

Creating a StepZen GraphQL API

With StepZen, you can create a GraphQL API for every data source, including REST APIs, databases, and more. In this section, we will create a GraphQL API that uses the Auth0 JWT to authenticate the user. The GraphQL API will fetch the user's profile information from the Auth0 API.

First, we need to create a new StepZen project. To do this, create a new directory called stepzen in the root of your project and run the following command in your terminal:

bashstepzen init api/jwt-login-flow`

This will create a new StepZen configuration file and set the endpoint name to api/jwt-login-flow. You can also choose to use a different name if you prefer.

To set up the StepZen GraphQL API, we need to complete the following steps:

Create a new schema file called api.graphql. This file will contain the GraphQL schema for the API, including a query to get user information from the Auth0 API. Replace the value for YOUR_AUTH0_DOMAIN with the domain of your Auth0 account:

`graphql
type User {
email: String
email_verified: Boolean
name: String
nickname: String
picture: String
sub: String
updated_at: DateTime
}

type Query {
me: User
@rest(
endpoint: "https://YOUR_AUTH0_DOMAIN/userinfo"
forwardheaders: ["Authorization"]
)
}
`

StepZen needs to have an index.graphql that references the api.graphql file. Create a new file called index.graphql and add the following code to it:

graphql schema @sdl(files: ["api.graphql"]) { query: Query }

To verify the Auth0 JWT, we need to create a new file called config.yaml. In this file, we'll add the configuration to valide the JWT using the JSON Web Key Set (JWKS) endpoint from Auth0 and the configuration to protect the GraphQL query me so authenticated users can only access it. Replace the value for YOUR_AUTH0_DOMAIN with the domain of your Auth0 account:

`yaml

Add the JWKS endpoint

deployment:
identity:
jwksendpoint: 'https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json'

Set the policies

access:
policies:
- type: Query
policyDefault:
condition: true
rules:
- condition: '?$jwt' # Require JWT
fields: [me] # Define fields that require JWT
`

Now run the following command to deploy and run your StepZen project:

bashstepzen start`

In your terminal, you should see a message that includes the URL of your GraphQL API. Copy the URL (which starts with https://YOUR_USERNAME.stepzen.net/api/****** and paste it into the .env file:

`bash

Your StepZen endpoint

STEPZEN_ENDPOINT='YOUR_STEPZEN_ENDPOINT'
`

That's it! We now have a working GraphQL API that can be used to validate the Auth0 JWT and fetch user information from the Auth0 API.

In the next section, we'll use this GraphQL API to fetch the user's profile information in the Next.js application.

Fetching user information in the Next.js application

In this section, we will use the GraphQL API that we created in the previous section to fetch the user's profile information in the Next.js application. We'll take the token from Auth0 using the library nextjs-auth0 to authenticate the user in the GraphQL API.

To do this, we need to complete the following steps:

Create a new file called pages/api/graphql/index.ts. This file will be the API route to send requests to the StepZen GraphQL API. It uses the withApiAuthRequired function from the nextjs-auth0 library, so the JWT will be available in the request, which we can extract using the getAccessToken function. We're using an API route here as exectuting the data fetching server side is the recommended way to fetch data in Next.js. This JWT will then be forwarded to the GraphQL API together with the GraphQL query. You can add the following code to this file:

`ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { withApiAuthRequired, getAccessToken } from '@auth0/nextjs-auth0';

export default withApiAuthRequired(async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
const { accessToken } = await getAccessToken(req, res);

const headers = {
Authorization: Bearer ${accessToken},
'Content-Type': 'application/json',
};

const body = req.body;

try {
const response = await fetch(process.env?.STEPZEN_ENDPOINT || '', {
method: 'POST',
headers,
body,
});

const json = await response.json();

res.status(200).json(json);

} catch (e: unknown) {
const message = (e as Error).message;

res.status(500).json({ error: message });

}
});
`

You can also generate a code snippet to connect to a StepZen GraphQL API from the StepZen dashboard. You can find this under the Explorer tab in the left pane of the dashboard by clicking on the Connect button in the top navigation.

In the pages/index.tsx file, we're using the new API route to fetch the user's profile information. When sending a request to this API route, we need to pass along the GraphQL query to get the user's name and picture. You can add the following code to this file:

`tsx
export default function Home() {
const [userData, setUserData] = useState name: string;
picture: string;
}>(null);

useEffect(() => {
async function fetchData() {
const res = await fetch('/api/graphql', {
method: 'POST',
body: JSON.stringify({
query: query { me { name picture } },
}),
});
const json = await res.json();

  if (json?.data?.me) setUserData(json.data.me);
}

fetchData();

}, [setUserData]);

return (
// ...
);
}
`

After retrieving the user's profile information, we can display it in the UI. You can add the following code to the pages/index.tsx file:

tsx return ( <main className={styles.main}> <div className={styles.center}> {userData ? ( <div className={styles.profile}> <img src={userData.picture} alt={${userData.name}'s profile picture} width={200} height={200} /> <p> <strong>Welcome {userData?.name}!</strong>{' '} <a href='/api/auth/logout'>Logout</a> </p> </div> ) : ( <Link href='/api/auth/login' className={styles.loginButton}> <span className={styles.auth0Logo} /> Login with Auth0 </Link> )} </div> </main> )

Next.js recommends using the Image component from next/image to render images. However, when rendering remote sources, you need to allow access to the remote URLs of these sources. Therefore, we're using the img tag instead.

Finally, we need to add the styling for the profile information. You can add the following code to the Home.module.css file:

`css
.profile {
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
margin-top: 20px;
}

.profile img {
border-radius: 50%;
margin-bottom: 20px;
}

.profile a {
color: #eb5424;
text-decoration: underline;
}
`

Now, if you open the application in the browser again and click on the Login with Auth0 button, you should be redirected to the Auth0 login page. After logging in, you should see the user's profile information in the UI.

As a finishing touch, we can show a loading indicator while the application checks if the user is authenticated and fetches the user's profile information. Therefore the useUser hook should be imported from @auth0/nextjs-auth0/client and the isLoading property should be used to check if the user is authenticated. You can add the following code to the pages/index.tsx file:

`tsx
import { useEffect, useState } from 'react';
import Head from 'next/head';
import Link from 'next/link';
import { useUser } from '@auth0/nextjs-auth0/client';
import styles from '@/styles/Home.module.css';

export default function Home() {
const { isLoading } = useUser();

// ...

return (

{isLoading ? (
Loading...
) : (

{
// ...
}

)}

);
}
`

Great! With this, we've implemented the login flow using Auth0 and StepZen. You can find the complete source code for this blog post on GitHub.

Next Steps?

The flow we've implemented in this blog post is a typical pattern for frontend applications that want to provide a secure way to authenticate users. The application uses the @auth0/nextjs-auth0 package to handle the authentication flow and a StepZen GraphQL API to verify the JWT on the server side. This way, the application can use the user's profile information on both the client side and in requests to the GraphQL API.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Comparing GraphQL Directives: Type System Vs. Executable Directive Locations

Roy Derks — Wed, 01 Feb 2023 16:12:17 +0000

Have you ever wondered why some directives have to be added to your GraphQL schemas while others you can only use in runtime? That's because there are two types of directive locations: type system directive locations and executable directive locations.

Earlier, we wrote about the different directives there are in GraphQL. This post will recapture what directives are and examine the difference between the different locations directives can be applied to.

Remind me, what is a GraphQL Directive?

Directives in GraphQL offer a means to change runtime execution and type validation in a GraphQL document. You can apply directives to many different locations in a GraphQL document, such as fields, fragments, and operations. They allow you to modify the behavior of GraphQL's execution by providing options that are not available through field arguments. For instance, you can conditionally include or exclude a field using directives, as you'll learn in this post.

You can use built-in or custom directives when building or consuming a GraphQL API. Built-in directives are defined by the GraphQL specification, while custom directives are defined by the GraphQL service or tool you use. Let's look at some of the built-in directives.

Built-in Directives

The GraphQL specification defines a set of built-in directives. Directives have a specific name and can accept values of any input type as arguments. They can be applied to, for example, types, fields, fragments, and operations.

The following list has all the built-in directives that are defined by the GraphQL specification:

@skip: This directive can be used to exclude fields from a query operation conditionally.
@include: Does the opposite of @skip and can be used to include fields in a query operation conditionally.
@deprecated: This directive can mark a field or an enum value as deprecated and can provide a reason for deprecation to the client.
@specifiedBy: This directive can be used to provide a URL for the specification of a custom scalar.

Note: As GraphQL evolves, new execution capabilities may be introduced and exposed through directives. The directives @defer and @stream have been announced by the GraphQL Working Group but aren't listed in the latest draft of the GraphQL specification.

GraphQL services and tools can also provide custom directives beyond those already mentioned. We'll learn more about custom directives in the next section.

Custom Directives

Custom directives can be used to extend the functionality of GraphQL and are the preferred way to add custom behavior to a GraphQL API. Different GraphQL server and client implementations are already using custom directives to add additional functionality to GraphQL.

For example, at StepZen, we have defined custom directives to connect with your data sources, such as the @rest, @dbquery, and @graphql directives. When using StepZen to develop your GraphQL API, you can use these directives to connect to REST APIs, databases, and other GraphQL APIs. Additionally, we have defined the @materializer and @sequence directives to mix and match data from multiple data sources in a single type.

But next to built-in and custom directives, there is another distinction to be made between directives: the location they are used in. In the next section, we'll examine the difference between directives applied to type system and executable locations in GraphQL.

Type System Directive Locations vs. Executable Directive Locations

Directives in GraphQL can be applied to different locations, where the GraphQL Specification makes a distinction between type system directive locations and executable directive locations. Directives applied to either of these locations have the same syntax; therefore, their location determines how a GraphQL implementation handles them. However, a directive may support both type system and executable locations, though typically, a single directive supports only one location. For example, @skip only supports executable directive locations.

Let's look at the locations where directives can be applied and see examples for both types.

Directives that apply to the type system

Directives that apply to the type system are used to annotate a schema, object type, or field definition written in GraphQL SDL (schema definition language) when building a GraphQL server. Both built-in and custom directives can be used in type system directive locations, and GraphQL server implementations can then use these annotations to take additional actions. Therefore, type system directive locations are also called "schema directives" as they only exist on the GraphQL schema itself.

The following locations in a GraphQL schema are valid type system directive locations:

SCHEMA
SCALAR
OBJECT
FIELD_DEFINITION
ARGUMENT_DEFINITION
INTERFACE
UNION
ENUM & ENUM_VALUE
INPUT_OBJECT & INPUT_FIELD_DEFINITION

Examples of directives that apply to the type system include @deprecated, a built-in directive that can mark a field as deprecated. Let's see what it looks like in a schema:

type User {
  id: ID!
  name: String! @deprecated(reason: "Use the firstName and lastName field instead")
  firstName: String!
  lastName: String!
  email: String!
}

In the example above, the @deprecated directive marks the name field as deprecated. The reason argument provides a reason for deprecation available to services that introspect the schema. The client could then, for example, warn the user that the field name is deprecated and shouldn't be used anymore.

When you would look up the User type in the documentation generated by GraphiQL, you should see warnings about using the field name:

Another example of a directive that can be applied to the type system is @rest, a custom directive only available in StepZen GraphQL implementations. The data for the User type in the example above is fetched from a REST API using the @rest directive, which is defined in the following way on a query field in a GraphQL schema:

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
    @rest(url: "https://jsonplaceholder.typicode.com/users/$id")
}

When you run an operation that includes the user field, the StepZen GraphQL API fetches the data from the REST API and returns it to the client. The @rest directive is applied to a type system location because it annotates the user field in the schema. It lets you declaratively define how the data for the user field should be fetched, rather than having to write a resolver function, as you might expect from other GraphQL server implementations.

Directives that apply to execution

You can use directives that apply to execution to modify the behavior of an operation, field, or fragment in runtime execution. For example, directives that apply to execution can include or exclude fields or perform additional data processing before the response is returned.

Executable directive locations in GraphQL are:

QUERY
MUTATION
SUBSCRIPTION
FIELD
FRAGMENT_DEFINITION & FRAGMENT_SPREAD
INLINE_FRAGMENT
VARIABLE_DEFINITION

Similar to directives that apply to the type system directives, both built-in and custom directives can be applied to executable locations. Most built-in directives are executable, such as @skip and @include, which you can use to include or exclude fields in an operation conditionally.

Let's see what the @include directive looks like in a query operation:

query me($showName: Boolean!) {
  me {
    id
    firstName @include(if: $showName)
    lastName @include(if: $showName)
    email
  }
}

The @include directive conditionally includes the firstName and lastName fields in the response. The if argument specifies a boolean value determining whether to include the field in the response. In the example above, the if argument is set to a variable $showName, which is defined in the operation variables. The variable's value can be set to true or false to include or exclude the fields in the response.

When you'd pass this operation to a GraphQL API, the response should include the fields firstName and lastName in the response if the value of the variable $showName is set to true as you can see in the screenshot below:

Another example of an executable directive is @sort, a custom directive only available in StepZen GraphQL implementations.

With the @sort directive, you can sort the data returned by a field in a GraphQL operation. You can use the @sort directive on a field that returns either a list of leaf fields or a list of objects.

For example, let's say you have a products field that returns a list of tags. You can use the @sort directive to sort the tags by alphabetical order:

query {
  products {
    tags # ['c', 'b', 'a', null]
  }
}

Will be transformed to this when the @sort directive is used:

query {
  products {
    tags @sort # [null, 'a', 'b', 'c']
  }
}

Next to a list of leaf fields, the same @sort directive can be applied to a field that returns a list of objects. You can find more information on using the @sort directive in the documentation.

Summary

In this blog post, you learned about built-in and custom directives and how they can be applied to different locations in GraphQL. These locations are either type system or executable locations. Directives applied to the type system directives are used in GraphQL Schema Definition Language (SDL) only. At the same time, directives applied to executable locations are used to modify the response of GraphQL in runtime execution.

Want to learn more about building and consuming GraphQL APIs? Follow StepZen on Twitter or join our Discord community to stay updated about our latest developments.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Authenticating GraphQL APIs with OAuth 2.0

Roy Derks — Wed, 25 Jan 2023 17:33:58 +0000

There are many different ways to handle authentication in GraphQL, but one of the most common is to use OAuth 2.0 - and, more specifically, JSON Web Tokens (JWT) or Client Credentials.

In this blog post, we'll look at how to use OAuth 2.0 to authenticate GraphQL APIs using two different flows: the Authorization Code flow and the Client Credentials flow. We'll also look at how to use StepZen to manage authentication.

What is OAuth 2.0?

But first, what is OAuth 2.0? OAuth 2.0 is an open standard for authorization that allows one application to let another application access certain parts of a user's account without giving away the user's password. There are different ways to set up this type of authorization, called "flows", and it depends on the type of application you are building.

For example, if you're building a mobile app, you will use the "Authorization Code" flow. This flow will ask the user to permit the app to access their account, and then the app will receive a code to use to get an access token (JWT). The access token will allow the app to access the user's information on the website. You might have seen this flow when you log in to a website using a social media account, such as Facebook or Twitter.

Another example is if you're building a server-to-server application, you will use the "Client Credentials" flow. This flow involves sending the website's unique information, like a client ID and secret, to get an access token (JWT). The access token will allow the server to access the user's information on the website. This flow is quite common for APIs that need to access a user's data, such as a CRM or a marketing automation tool.

Let's have a look at these two flows in more detail.

Authorization Code Flow (using JWT)

The most common way to use OAuth 2.0 is with the Authorization Code flow, which involves using JSON Web Tokens (JWT). As mentioned above, this flow is used when you want to build a mobile or web application that needs to access a user's data from a different application.

For example, if you have a GraphQL API that allows users to access their data, you can use a JWT to verify that the user is authorized to access the data. The JWT could contain information about the user, such as the user's ID, and the server can use this ID to query the database and return the user's data.

You would need a frontend application that can redirect the user to the authorization server and then redirect the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for an access token (JWT) and then use the JWT to make requests to the GraphQL API.

The JWT can be sent to the GraphQL API in the Authorization header:

curl https://USERNAME.stepzen.net/api/hello-world/__graphql \
   --header "Authorization: Bearer JWT_TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw '{
     "query": "query { me { id username } }"
   }'

And the server can use the JWT to verify that the user is authorized to access the data.

The JWT can also contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make. But we'll look at this in more detail after discussing the Client Credentials flow.

Client Credentials Flow

The Client Credentials flow is used when you want to build a server-to-server application, like an API, that needs to access information from a different application. It also relies on JWT.

As mentioned above, this flow involves sending the website's unique information, like a client ID and secret, to get an access token. The access token will allow the server to access the user's information on the website. Unlike the Authorization Code flow, the Client Credentials flow doesn't involve a (frontend) client. Instead, the authorization server will directly communicate with the server that needs to access the user's information.

Image from Auth0

The JWT can be sent to the GraphQL API in the Authorization header, in the same way as for the Authorization Code flow.

In the next section, we'll look at how to implement both the Authorization Code flow and the Client Credentials flow using StepZen.

Using StepZen to Manage Authentication

By default, StepZen uses API Keys to authenticate requests. This is a developer-friendly way to authenticate requests that don't require an external authorization server. But if you want to use OAuth 2.0 to authenticate requests, you can use StepZen to manage authentication. Similar to how you can use StepZen to build a GraphQL schema for all your data in a declarative way, you can also manage authentication declaratively.

Implement Authorization Code Flow (using JWT)

To implement the Authorization Code flow, you must set up both a (frontend) client and an authorization server. You can use an existing authorization server, such as Auth0, or build your own.

You can find a complete example of using StepZen to implement the Authorization Code flow in the StepZen GitHub repository.

StepZen can validate the JWTs generated by the authorization server and send them to the GraphQL API. You only need the authorization server to validate the user's credentials to generate a JWT and StepZen to validate the JWT.

Let's have another look at the flow we discussed above:

In this flow diagram, you can see that the frontend application redirects the user to the authorization server (from Auth0) and then turns the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for a JWT and then use that JWT to make requests to the GraphQL API.

StepZen will validate the JWT that is sent to the GraphQL API in the Authorization header by configuring the JSON Web Key Set (JWKS) endpoint in the StepZen configuration in the config.yaml file in your project:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'

The JWKS endpoint is a read-only endpoint that contains the public keys to verify a JWT. The public keys can only be used to validate the tokens, as you would need the private keys to sign the tokens, which is why you need to set up an authorization server to generate the JWTs.

You can then limit the fields and mutations a user can access by adding Access Control rules to the GraphQL schema. For example, you can add a rule to the me query to only allow access when a valid JWT is sent to the GraphQL API:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '?$jwt' # Require JWT
          fields: [me] # Define fields that require JWT

This rule only allows access to the me query when a valid JWT is sent to the GraphQL API. If the JWT is invalid, or if no JWT is sent, the me query will return an error.

Earlier, we mentioned that the JWT could contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make.

You can add a rule to the me query to only allow access when a user has the admin role:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '$jwt.roles:String has "admin"' # Require JWT
          fields: [me] # Define fields that require JWT

To learn more about implementing the Authorization Code Flow with StepZen, look at the Easy Attribute-based Access Control for any GraphQL API article on the StepZen blog.

Implement Client Credentials Flow

You will also need to set up an authorization server to implement the Client Credentials flow. But instead of redirecting the user to the authorization server, the server will directly communicate with the authorization server to get an access token (JWT).

You can find a complete example for implementing the Client Credentials flow in the StepZen GitHub repository.

First, you must set up the authorization server to generate the access token. You can use an existing authorization server, such as Auth0, or build your own.

In the config.yaml file in your StepZen project, you can configure the authorization server to generate the access token:

# Add the JWKS endpoint
deployment:
  identity:
    jwksendpoint: 'https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json'

# Add the authorization server configuration
configurationset:
  - configuration:
      name: auth
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      audience: YOUR_AUDIENCE

The client_id, client_secret and audience are required parameters for the authorization server to generate the access token (JWT). The audience is the API's identifier for the JWT. The jwksendpoint is the same as the one we used for the Authorization Code flow.

In a .graphql file in your StepZen project, you can define a query to get the access token:

type Query {
  token: Token
    @rest(
      method: POST
      endpoint: "YOUR_AUTHORIZATION_SERVER/oauth/token"
      postbody: """
      {
        "client_id": "{{ .Get "client_id" }}",
        "client_secret": "{{ .Get "client_secret" }}",
        "audience": "{{ .Get "audience" }}",
        "grant_type": "client_credentials"
      }
      """
    )
}

The token mutation will request the authorization server to get the JWT. The postbody contains the parameters that are required by the authorization server to generate the access token.

You can then use the JWT from the response on the token mutation to request the GraphQL API, by sending the JWT in the Authorization header.

But we can do better than that. We can use the @sequence custom directive to pass the response of the token mutation to the query that needs authorization. This way, we don't need to send the JWT manually in the Authorization header on every request:

type Query {
  me(access_token: String!): User
    @rest(
      endpoint: "YOUR_API_ENDPOINT"
      headers: [{ name: "Authorization", value: "Bearer $access_token" }]
    )
  profile: User @sequence(steps: [{ query: "token" }, { query: "me" }])
}

The profile query will first request the token query to get the JWT. Then, it will send a request to the me query, passing along the JWT from the response of the token query as the access_token argument.

As you can see, all configuration is set up in a single file, and you can use the same configuration for both the Authorization Code flow and the Client Credentials flow. Both are written declarative, and both use the same JWKS endpoint to request the authorization server to verify the tokens.

What's next?

In this blog post, you learned about common OAuth 2.0 flows and how to implement them with StepZen. It's important to note that, as with any authentication mechanism, the details of the implementation will depend on the application's specific requirements and the security measures that need to be in place.

StepZen GraphQL APIs are default protected with an API key but can be configured to use any authentication mechanism. We'd love to hear what authentication mechanisms you use with StepZen and how you use them. Ping us on Twitter or join our Discord community to let us know.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Compose Data from Fauna and GitHub using GraphQL and StepZen

Roy Derks — Wed, 16 Nov 2022 15:07:54 +0000

You can find the complete code example for this blog on the StepZen GitHub page.

Data composition is getting more and more important for modern APIs. Companies no longer store data in just one database; more often, data comes from multiple sources. For example, a database or third-party APIs with all sorts of specifications. In GraphQL, the composition of data in APIs is also called federation. This post will teach you how to compose data from Fauna and GitHub using GraphQL and StepZen.

To show how to compose (or federate) data, we'll be combining data from Fauna and GitHub. Fauna is a distributed document-relational database delivered as a global API. Fauna can be queried using Fauna Query Language (FQL), and also provides a native GraphQL API. GitHub is a popular code hosting platform for version control and collaboration, and it also provides a GraphQL API. The API we'll build in this post will take data from a GitHub repository and enrich it with data stored in Fauna using StepZen. StepZen is a GraphQL-as-a-Service platform that allows you to compose data from multiple sources into one API declaratively. The diagram below shows how the data will be composed.

You can query the GraphQL API created with StepZen from any application you connect. For example, you can use the API in a web application to display a list of repositories with their stars and forks. You can also use the API in a mobile application to show the same data.

First, we'll explore the GitHub GraphQL API and see how we can query it. Then we'll set up and seed a Fauna database with data. Finally, StepZen will be used to combine the data from Fauna and GitHub and return it as a single GraphQL response.

Explore the GitHub GraphQL API

In this post, we'll be building a GraphQL API that composes data from Fauna and GitHub. To get started, we'll explore the GitHub GraphQL API. The GitHub GraphQL API is a public API that you can use to query data about repositories, users, organizations, and more. The API is documented on GitHub and can be queried using GraphiQL.

To get started, we'll query the API to get the names and descriptions of users' repositories. The query below will return the name and description of the repositories of the user octocat. You can replace the login argument with your own GitHub username.

{
  user(login: "octocat") {
    repositories(first: 5) {
      edges {
        node {
          id
          name
          description
        }
      }
    }
  }
}

This query will return the data as seen in the screenshot below.

When you're not using the Github GraphiQL explorer to query the GraphQL API, you should create a personal access token and use it in the Authorization header of your GraphQL requests. You can create a personal access token in your Github settings.

From the Github GraphiQL explorer, you can find all the fields that you can query for the GitHub repositories. This aside, we'll set up a Fauna database next that will contain our data about the repositories. We will use the data from Fauna to enrich the data from GitHub.

Set up Fauna

Create a Fauna account

To get started with Fauna, you need to sign up here, for example, by signing up using your GitHub account. After you've signed up, you'll be redirected to the Fauna dashboard. From the dashboard, you can create a database by clicking on the + Create Database button

Give the database a name, for example, stepzen-demo and select a region where Fauna should host the database. GraphQL APIs created on StepZen free plan are hosted in the US, so we will choose that region.

The Fauna dashboard will show the database you created. From this page, you can also add data to the database. Fauna is a document-based database, so data is stored as collections in the database instead of tables. In the next step, we will create a collection and add some data. For this, you can use the dashboard or the tool fauna-shell.

Create a collection

To create the API, we will need some data to work with, so we first need to create a collection before storing data. A collection is a container for documents, the actual data stored in Fauna.There are two ways to seed your Fauna database with the initial data, via the dashboard or your terminal using fauna-shell.

Let's use the dashboard to create our first collection. From the dashboard, we can upload a GraphQL schema to create the collection and the documents. The schema is a GraphQL schema but not a GraphQL API, and uses it to create the collection and documents that will be stored in Fauna.

To create a collection, click on the GraphQL tab in the left menu. You can upload a GraphQL schema on this page by clicking on the Import Schema button. The file you can upload here should be in .gql or .graphql format, so you can create a new file in your editor and copy the following schema.

type Highlight {
  repository: Repository! @relation
}

type Repository {
  owner: String!
  name: String!
  coverImage: String
  shortDescription: String
}

type Query {
  highlights: [Highlight]!
  repositories: [Repository]!
}

In this post, we'll build a GraphQL API that returns a list of highlighted GitHub repositories enriched with data from Fauna, such as a cover image and a short description. The schema above defines the data structure of the documents that will be stored in Fauna. The Highlight collection will contain documents with a field repository related to the Repository collection. The Repository type defines the data structure of a repository (e.g. the enriched data) and has a link to the data from GitHub via the owner and name fields. Let's import some of the data from GitHub to Fauna.

Add data to the collections

After you've uploaded the schema, you can add data to the collections. To add data to the Repository collection, we will use the GraphQL API that Fauna provides. To do this, click on the GraphQL tab in the left menu and click on the Playground button. Clicking this button will open the GraphQL playground, similar to the one from Github, where you can write queries to interact with the Fauna GraphQL API.

Looking at the Docs tab in the playground, you can see the schema you uploaded earlier. You can also see the queries and mutations that you can use to interact with the Fauna GraphQL API. Fauna has automatically generated queries and mutations based on your imported schema, for example, to get a single repository by its id or to create/update a repository. Also, the queries to get all repositories and highlights are extended with pagination fields.

We'll be using the generated mutation createRepository mutation to add the data from GitHub to Fauna. The mutation below will create a new document in the Repository collection. Remember the query we ran earlier to get the id, name, and description of the repositories of the user octocat? We'll use this data to store the owner and name fields from GitHub in Fauna. The coverImage and shortDescription fields will remain empty.

mutation {
  createRepository(data: {
    owner: "octocat",
    name: "hello-world"
  }) {
    _id
  }
}

After you've run the mutation, you can see the new document in the Repository collection. You can also see the _id field that Fauna has generated for the document. This _id field is used to identify the document in Fauna, so we'll be using this _id field to link the document in the Highlight collection to the document in the Repository collection:

mutation {
  createHighlight(
    data: { repository: { connect: "343960570233356362" } }
  ) {
    repository {
      _id
    }
  }
}

The repository field in the Highlight collection relates to the Repository collection, meaning you could query this relationship using the Fauna GraphQL API.

As we now have two GraphQL APIs, let's continue to the final part of this post and combine them into one GraphQL API using StepZen.

Use StepZen to GraphQL APIs

Combining the two GraphQL APIs into one GraphQL API is done using StepZen. StepZen is a GraphQL API service that allows you to create GraphQL APIs for your data sources (SQL, NoSQL, REST, and GraphQL) or to combine multiple GraphQL APIs into one GraphQL API. StepZen can be used via a CLI and has a generous free plan.

The act of combining or composing GraphQL APIs is also called federation. StepZen can also be used as a GraphQL federation service, which means combining multiple GraphQL APIs into one GraphQL API. The GraphQL APIs that are combined into one GraphQL API is called subgraphs, and for this section, we'll be using the GitHub GraphQL API and Fauna as a subgraph.

Set up StepZen

To use StepZen, you should download and install the CLI from npm, by running the following command:

`npm install -g stepzen`

After installing, you can choose to run StepZen locally using Docker or in the cloud by signing up for a free account at stepzen.com. For this example, we'll be using the cloud version, for which you can sign up for a free account using your GitHub account.

Import the GitHub GraphQL API

Inside a new project, we'll be using the CLI first to import the Github GraphQL using the following command:

`stepzen import graphql`

And answer the prompts with the values below, where the prefix github is added to all types and operations. Using prefixes will prevent naming conflicts once we import Fauna as a subgraph.

? What is the GraphQL endpoint URL?
https://api.github.com/graphql

? Prefix to add to all generated type names (leave blank for none)
github_

? Should type prefix be added to query and mutation fields as well?
Yes

? Add an HTTP header, e.g. Header-Name: header value (leave blank for none)
Authorization: bearer ghp_************

To query the GraphQL API from Github, you need to pass along a personal access token and pass it as an Authorization header to the CLI import command. You can create a personal access token in your GitHub settings.

The StepZen CLI will generate a schema containing the types and queries that are available in the GitHub GraphQL API. You can see the generated types and queries in the file graphql/index.graphql in the project directory. Also, the CLI will generate a config.yaml file that contains the GitHub personal access token. You can start the StepZen server by running the following command:

`stepzen start`

The start command will deploy the GraphQL schemas to the StepZen cloud and start the StepZen server. The first time you run this command, you need to provide an endpoint name, api/with-fauna. You can now open the GrapihQL playground from the link in the terminal to query the GitHub GraphQL API through StepZen.

Import the Fauna GraphQL API

Second, we also need to import the GraphQL API for the Fauna database into StepZen. To do this, we'll be using the stepzen import graphql command again, but this time we'll use the connection details to the Fauna GraphQL API.

You can find the connection details in the Fauna dashboard under the "GraphQL" tab. You can copy the endpoint from the "Endpoint" field at the top and the authorization token under "HTTP headers".

And enter them in the prompts of the StepZen CLI:

? What is the GraphQL endpoint URL?
https://graphql.us.fauna.com/graphql

? Prefix to add to all generated type names (leave blank for none)
fauna_

? Should type prefix be added to query and mutation fields as well?
Yes

? Add an HTTP header, e.g. Header-Name: header value (leave blank for none)
Authorization: Basic ****************

This time we used the prefix fauna_ to prevent any naming conflicts in the types and operations, for example, the Repository type from the GitHub GraphQL API and the Repository type from the Fauna GraphQL API.

After importing the Fauna GraphQL API, you can see the generated types and queries in the file graphql-01/index.graphql in the project directory. The token for the Fauna GraphQL API is also stored in the config.yaml file.

Also, we can query the highlights from the Fauna GraphQL API from StepZen, as you can see in the screenshot below:

The final step is to compose the data from the two GraphQL APIs by combining them into one GraphQL API. This is done by adding a extends.graphql file in the project directory, which will contain the types and queries that will be used to query the data from the two GraphQL APIs.

Compose data using StepZen

We're now able to query both the GitHub GraphQL API and the Fauna GraphQL API individually using StepZen. To compose the data in one single GraphQL API, we'll create a new file called extends.graphql file. This file will contain the types and queries that we will use to query the data from the two GraphQL APIs.

Inside this new file, you should add the following code block:

extend type fauna_Repository {
  githubDetails: github_Repository
    @materializer(
      query: "github_repository"
      arguments: [
        { name: "owner", field: "owner" }
        { name: "name", field: "name" }
      ]
    )
}

This will extend the type fauna_Repository, which is the type Repository from the Fauna GraphQL API, with all the fields returned by the query github_repository. The query github_repository is the query that is generated by the StepZen CLI when importing the GitHub GraphQL API. The arguments that are passed to the query are the fields owner and name from the fauna_Repository type.

We can now use the githubDetails field to query the GitHub GraphQL API, and we will use the @materializer directive to query the github_repository query from the GitHub GraphQL API.

You can also query a single highlight and get all the other fields available on the return type of github_repository, which is github_Repository. StepZen will ensure that the data from the two GraphQL APIs are composed into one single GraphQL API, and no unnecessary data is requested or returned.

Conclusion

In this post, we've used StepZen to combine the GitHub GraphQL API and the FaunaGraphQL API into one single GraphQL API. This makes it possible to query the data from both GraphQL APIs in one query. Composing data in GraphQL is also called federation. We've learned how to set up a GraphQL API with Fauna and fill it with data from GitHub, and how to use StepZen to combine the data from two GraphQL APIs into one single GraphQL API. And how to extend types with the @materializer directive.

You can find the complete code example for this blog post on the StepZen GitHub page.

Follow StepZen on Twitter or join our Discord community to stay updated about our latest developments.

Extending types For Data Modelling in GraphQL

Roy Derks — Tue, 08 Nov 2022 18:35:14 +0000

GraphQL is very good at helping you compose your data from different data sources, for example, by using federation. Type extensions can be very helpful when you're using GraphQL as a data layer or gateway for all your data. GraphQL type extensions allow you to add or replace fields on types that already exist in your schema. This way, you can better organize your data from different sources.

Let's explore how type extensions help with data modeling in GraphQL.

What are Type Extensions

Type extensions help you with data modeling in GraphQL, primarily when you work with different data sources. Or want to modify third-party data types that you cannot change directly.

In the GraphQL specification, you can find multiple definitions of type extensions, where "object extensions" are the most common ones. The section 3.6.3. Object Extensions describes how you can use the extend keyword to add or replace fields to an object type.

An example of extending a type would be to the following:

type Person {
  id: String
  name: String
  age: Int
}

extend type Person {
  email: String
}

The type Person will now have the fields id, name, age, and email. When we go back to the earlier statement about data composition when working with multiple data sources, this example would be perfect for a situation where the fields id, name, and age come from one source of data (for example, a database). And email comes from another data source, let's say a CRM.

In StepZen, this means that the GraphQL schema would look something like this:

type Person {
  id: String
  name: String
  age: Int
}

extend type Person {
  email: String 
    @materializer (query: "getPersonEmail", arguments: [{name: "personId", field: "id"}]
}

type Query {
  getPerson(id: ID!): Person
    @dbquery(
      type: "mysql"
      table: "person"
      configuration: "mysql_config"
    )
  getPersonEmail(personId: ID!): String
    @rest (endpoint: "https://some.crm.com/api/person/$personId/email")
}

The GraphQL schema above will get the fields for the type Person from the MySQL database using a @dbquery connector. For the extended field email it will use @materializer to get the data from a CRM system using its REST API.

If the database contained an email field, it could also be overwritten when using type extensions, as StepZen will always prefer the extended object types.

GraphQL also supports inheritance, which is often seen as an alternative to type extensions. Inheritance is focused on reusing rather than extending types, as you'll learn in the next section.

Extending types versus inheritance

There's a difference between type extensions and inheritance. You can use inheritance to compose your data in many programming languages or type systems, and GraphQL is no different.

With inheritance in GraphQL, you can reuse field definitions by using interfaces, meaning you can assign a set of fields to every type that implements this interface. The implementations of this interface only share the types of the interface.

Suppose you have a company that has both full-time employees and seasonal employees that only work in the winter or summer season.

interface Employee {
  id: ID
  name: String
  email: String
}

type FullTimeEmployee implements Employee {
  id: ID
  name: String
  email: String
  monthlyWage: Float
}

type SeasonalEmployee implements Employee {
  id: ID
  name: String
  email: String
  hourlyWage: Float
  season: String
}

The interface Employee has the fields id, name, and email, which is the data the company stores for every employee for example in a database or CRM. Employees working full-time are paid a monthly wage, while a seasonal employee receives an hourly wage instead. Also, the company stores the season the employee is active in.

As both FullTimeEmployee and SeasonalEmployee are implementing the interface Employee, you have the certainty that the definitions of the fields id, name, and email are the same across all employees.

Conclusion

GraphQL can be used as a data layer or gateway to compose this data when working with multiple data sources. Modeling your data in this setup can be done by using type extensions or, in some cases, by using inheritance. This post described how you could use object extensions to extend a type with fields coming from a different data source and inheritance to reuse field definitions for different ones.

Want to try this out? Head over to the Getting Started section and start building your GraphQL API. Follow us on Twitter or join our Discord community to ask for help when you run into any issue.

Turn Your StepZen GraphQL APIs into REST with Kong

Roy Derks — Mon, 31 Oct 2022 10:32:40 +0000

GraphQL APIs are becoming the defacto API standard. But what if you want to use a GraphQL API in a legacy application that only supports REST? This blog post will show you how to use Kong to turn your StepZen GraphQL APIs into REST. Earlier, we published a blog post about how to use Kong as an API Gateway for StepZen GraphQL APIs, including using proxy caching. In this post, we will discuss another reason to use an API Gateway: to turn GraphQL APIs into REST API endpoints.

Why turn GraphQL APIs (back) into REST?

GraphQL is a great way to expose your data to your clients. It allows you to expose only the data your clients need and do so in a way that is easy to use. Although GraphQL might be the most efficient way to consume data in the frontend, it's not the only way to expose your data. REST is still a popular way to expose data, and many systems still rely on it. For example, when you need to integrate your API with a legacy system that only supports REST. Therefore, it might also make sense for your company to expose a REST API.

One way to do so is by calling your GraphQL API the same way as a REST API. Most GraphQL APIs are implemented over HTTP, meaning that the request to a GraphQL API has the same structure as a request to a REST API. The only difference is that every request needs to be a POST method and the request's body contains a GraphQL query.

Another way is to use an API Gateway to turn your GraphQL API into a REST API. You define the REST API endpoints and map GraphQL queries to these endpoints. This is a more efficient way to expose your GraphQL API as a REST API because you can keep control of the available REST endpoints, and can distribute them to you clients much more like a contract (which REST also is). You can use the API Gateway to expose your GraphQL API as a REST API and to do other things like caching, rate limiting, and authentication.

Using Kong to turn GraphQL APIs into REST APIs

Kong is an open-source API Gateway that you can use with all sorts of APIs, including GraphQL APIs. It helps you to manage your APIs and to do things like caching, rate limiting, and authentication. You can also use it to turn your GraphQL APIs into REST APIs, and we will go over how to do so.

Let's say you have a GraphQL API that converts one currency to another, such as the Frankfurter API in StepZen GraphQL Studio.

# https://graphqldd.stepzen.net/api/dd1cf47f51ac830fe21dc00ec80cee65/__graphql
query ConvertCurrencyByIP ($amount: Float!, $from: String!, $ip: String!) {
  converted: ipApi_location(ip: $ip) {
    countryCode
    price: priceInCountry(amount: $amount, from: $from)
  }
}

This query can transform a currency based on the IP address. For example, if you want to convert 100 GBP to USD, you can do so by calling the following query:

curl 'https://graphqldd.stepzen.net/api/dd1cf47f51ac830fe21dc00ec80cee65/__graphql' \
  -H 'authority: graphqldd.stepzen.net' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw $'{"query":"query ConvertCurrencyByIP($amount: Float\u0021, $from: String\u0021, $ip: String\u0021) { converted: ipApi_location(ip: $ip) { countryCode price: priceInCountry(amount: $amount, from: $from) } }","variables":{"amount":100,"from":"GBP","ip":"8.8.8.8"},"operationName":"ConvertCurrencyByIP"}' \

As StepZen has GraphQL implemented over HTTP, you could already use the call to this GraphQL like a REST API.

However, if you want to use an API Gateway to turn your GraphQL API into a REST API, you can do so by using Kong. In this article we explained how to use Kong as an API Gateway for a StepZen GraphQL API.

The request will look the same when you're using Kong, but the endpoint will be different. Instead of calling the GraphQL endpoint, you will call the Kong endpoint. The Kong endpoint will then call the GraphQL endpoint and return the result to the client, in example if you have a local instance of Kong available on localhost:8000, you can call the following query:

curl http://localhost:8000/price/ \
   --header "Content-Type: application/json" \
   --data '{"query": "query ($amount:Float!,$from:String!,$ip:String!){converted:ipApi_location(ip:$ip){countryCode price:priceInCountry(amount:$amount,from:$from)}}", "variables": {"amount":100,"from":"GBP","ip":"8.8.8.8"}}'

{
  "data": {
    "converted": {
      "countryCode": "US",
      "price": 115.69
    }
  }
}

To turn that query into a REST API endpoint, you can use the degraphql plugin that's available for Kong Enterprise. With this plugin, you can create a REST API endpoint and declaratively map the GraphQL query to the REST endpoint. After configuring the plugin, you can call the following endpoint:

curl -X POST http://localhost:8001/services/graphql-demo/degraphql/routes \
--data uri="/gbp/:ip/:amount" \
--data query='query($amount:Float!,$ip:String!){converted:ipApi_location(ip:$ip){countryCode price:priceInCountry(amount:$amount,from:"GBP")}}'

The uri parameter is used to create the REST endpoint you want to expose, where the :ip and :amount parameters are mapped to the parameters in the GraphQL query. The query parameter is the GraphQL query you want to call.

After registering the new REST endpoint to the plugin, you can call the following endpoint:

curl localhost:8000/price/gbp/8.8.8.8/100

{
  "data": {
    "converted": {
      "countryCode": "US",
      "price": 115.69
    }
  }
}

However, the response has the same structure as earlier for our GraphQL query. This structure is typical for GraphQL APIs but not REST APIs and provides no benefits over calling the GraphQL API directly. To change this, you can "unwrap" the response by using the jq plugin from Kong. You can configure this plugin to remove the data key from the response and return the data directly.

`curl localhost:8001/services/graphql-demo/plugins -d name=jq -d config.response_jq_program='.data' -d config.request_if_media_type='application/json; charset=utf-8'`

Now, when you call the REST endpoint, you will get the following response:

curl localhost:8000/price/gbp/8.8.8.8/100

{"converted":{"countryCode":"US","price":115.69}}

This is a much better response for a REST API; you can use this to expose your GraphQL API as a REST API. For a more detailed explanation of how to use Kong to turn GraphQL APIs into REST APIs, you can read this article on the Kong website.

Conclusion

This post shows how you can use Kong to turn your GraphQL APIs into REST APIs. Even though GraphQL is becoming the standard for any client-facing API, many legacy systems still use REST APIs. Using Kong as an API Gateway got GraphQL, you can expose your GraphQL API as a REST API, which these legacy systems can use. This is done by mapping a GraphQL query to a REST endpoint and then using the Kong plugins to transform the response to a REST API response.

Implementing Cursor-based Pagination For Every GraphQL API

Roy Derks — Mon, 17 Oct 2022 12:02:26 +0000

Implementing Cursor-based Pagination For Every GraphQL API

Backends often return a massive amount of data, and intaking all data simultaneously causes more overhead and increases the response time. Pagination preserves the application's performance by receiving small pieces of data in subsequent requests until the entire dataset is received.

When Facebook publicly released GraphQL as a client-driven API-based query language, it quickly gained hype because it allowed front-end developers to modify their backends easily. Applications using GraphQL are more efficient and work promptly on slow networks, and therefore, it is quickly replacing the traditional API architectures like REST. Pagination is an essential concept in GraphQL, but there aren't many resources on pagination in GraphQL.

In this post, we'll compare the different ways to handle pagination in GraphQL and learn how to configure a REST directive to perform cursor-based pagination for every REST API using StepZen.

TL;DR: You can find the complete documentation on paginating GraphQL using StepZen here.

Comparing Different Methods of Pagination in GraphQL

Pagination in GraphQL is not different from pagination in REST APIs, although some types of pagination better fit GraphQL. Before discussing the preferred pagination method in GraphQL, let's look at different pagination types. Typically, APIs offer three methods for pagination. These are:

1. Offset Pagination

Offset pagination consists of two primary parameters: limit and offset. The limit indicates the maximum number of results to show. And the offset denotes the position in the list from where the pagination starts.

Suppose you have a list of 100 students. If you set the limit parameter to 10 and offset to 20, the database engine will count from the 20th student and display the following ten students in each iteration. For instance, the first iteration will show the students from 20 to 30, then from 30 to 40, etc.

Although offset pagination is the most straightforward, it has a significant drawback. When some items are added or deleted, offset pagination results in repeated or missing data values.

Pros:

Most common way to do pagination in general.
Relatively simple implementation.
Most SQL-based databases support the limit and the offset variables, so it's easier to map values.

Cons:

Prone to data inconsistencies (repeated or missing data).
It doesn't provide information about more pages, total pages, or retrieval of previous pages.

2. Page Number Pagination

As the name specifies, page number pagination returns a single page per request. You all have seen a "next page" option when working with tables; each sheet shows the same number of results or entries. Similarly, page number pagination returns the same number of results per request.

Let's take an example to understand how it works. Page number pagination uses the after parameter to indicate the starting point for pagination. For instance, if you have a list of 30 students and set the after and the limit parameters to 23 and 5, respectively, then the output list will show a list of 5 students from the 23rd to 28th entry.

Page number pagination is more reliable as the upcoming results start from the last fetched values.

Pros:

Easier to implement.
It doesn't require complex logical analysis.

Cons:

Data inconsistencies.

3. Cursor Pagination

The third kind of pagination is cursor-based pagination. However, it is most complicated but is adaptable to dynamic data. Therefore, it is the preferred way to do pagination in GraphQL.

This method includes a specific parameter for the cursor. A cursor is nothing but a reference point that shows the position of an item in the database. The data are represented as nodes and a cursor as an edge in the graphical representation.

A cursor is a base64 encoded number. The query written for cursor-based pagination returns an object representation instead of a list.

Pros:

The preferred way to do pagination in GraphQL.
Provides valuable data for UX uses.
Allows reverse pagination.
No issues in the case of dynamic data as pagination are done to a specific row.

Cons:

It doesn't allow random access.
Needs complicated queries.

How to Implement Pagination in GraphQL using StepZen

Now you know about all the possible pagination methods and the preferred way of doing pagination in GraphQL, which is cursor-based pagination. If your REST API supports offset or page number pagination, you can easily implement cursor-based pagination in GraphQL using StepZen.

The two essential parameters you need to specify for every type of pagination are type and setters. The type parameters define the pagination style you want to implement. It has three possible values: PAGE_NUMBER, OFFSET, and NEXT_CURSOR. Next comes the setters parameters, which need to be pointed towards a field that indicates how many results or pages the response will output. You can find the list of all parameters with different pagination styles in the documentation.

Let's look at some examples:

1. Implementing Cursor Pagination for Offset

The below snippet illustrates how to implement GraphQL cursor-based pagination using StepZen for REST APIs supporting offset pagination. Note that the parameter first is set to the number of required results. The second parameter, after, is set to the starting point of the pagination.

customers(
  first: Int! = 20 
  after: String! = ""
): CustomerConnection
  @rest(
    endpoint:"https://api.example.com/customers?limit=$first&offset=$after"
    pagination: {
        type: OFFSET
        setters: [{field:"total" path: "meta.total_count"}]
      }
    )

Since it's the first request, the after parameter is equal to an empty string. The first parameter is set to 20, which means that the first 20 results will be returned. On the second request, you can change the value for after to be equal to the value of first from the previous request. Every new request will be a multiple of the first parameter.

2. Implementing Page Number Pagination

Take a look at the following code to get a better understanding of implementing cursor-based pagination in GraphQL using StepZen, when your REST API is relying on page number pagination:

customers(
  first: Int! = 20 
  after: String! = ""
): CustomerConnection
  @rest(
    endpoint:"https://api.example.com/customers?page=$after&per_page=$first"
    pagination: {
        type: NEXT_CURSOR
        setters: [{field:"nextCursor" path: "meta.next"}]
      }
    )

The above example illustrates some important aspects. The after parameter is set to an empty string, which indicates that it is the first request. In contrast, the first parameter is set to 20, meaning that 20 results will be returned per page. Remember, the value of the first parameter remains the same for subsequent requests as well. The after parameter in the upcoming request will be according to the page number you want to be returned. For instance, it is 3 for the third and 4 for the fourth page.

3. Implementing Cursor Pagination

Implementing cursor-based pagination is very similar to the other two pagination methods. The only difference is that you need to specify the type parameter as NEXT_CURSOR, and change the setters parameter to point towards the field that indicates the next cursor.

customers(
  first: Int! = 20 
  after: String! = ""
): CustomerConnection
  @rest(
    endpoint:"https://api.example.com/customers?first=$first&after=$after"
    pagination: {
        type: NEXT_CURSOR
        setters: [{field:"nextCursor" path: "meta.next"}]
      }
    )

This, of course, only applies if your REST API already supports cursor-based pagination.

How to Query Cursor Pagination in GraphQL

In the previous section, you've learned how to implement cursor-based pagination for any REST API using StepZen. Cursor-based pagination is for example, used by Relay, and is also supported by the StepZen GraphQL API. Cursor-based pagination is the preferred way to do pagination in GraphQL, as it provides valuable data for UX uses. But it comes with the downside of being more complex to query, as we saw in the first section.

Let's look at the Connection type that is used by cursor-based pagination:

type Customer {
  activities: [Activity]
  addresses: [Address]
  contacts: Contacts
  description: String
  designation: String
}

type CustomerEdge {
  node: Customer
  cursor: String
}

type CustomerConnection {
  pageInfo: PageInfo!
  edges: [CustomerEdge]
}

The CustomerConnection type is the one that is returned by the customers query. It contains a pageInfo field, which is of type PageInfo. The PageInfo type contains the following fields:

query MyQuery {
  customers {
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

These fields inform you about the current page, and whether there are more pages to be fetched. The endCursor and startCursor fields are the cursors that you need to use in the next request. The hasNextPage and hasPreviousPage fields indicate whether there are more pages to be fetched.

The edges field contains a list of CustomerEdge objects. The CustomerEdge type contains a node field of type Customer. To get the information about the customer, you would need to use the node field:

query MyQuery {
  customers(first: 3, after: "eyJjIjoiTzpRdWVyeTpwYXJrcyIsIm8iOjl9") {
    edges {
      node {
        id
        description
      }
    }
  }
}

The concept of "edges and nodes" is a bit confusing but very straightforward. It comes from the concept that everything in GraphQL is a graph. The edges field contains a list of CustomerEdge objects, information that is specific for this connection but not shared by all nodes. The CustomerEdge type contains a node field of type Customer. This is the actual customer information.

For Relay, you can find more information on GraphQL connections in the documentation.

Conclusion

GraphQL allows different kinds of pagination. But how does one decide which one will work best? GraphQL recommends using cursor-based pagination. However, it depends on the requirements of your application. If you are using a REST API already supporting cursor-based pagination, then it's a no-brainer. But if you are using a REST API that is not supporting cursor-based pagination, then you can use StepZen to implement it.

The common and the most straightforward kinds of pagination are offset and page number. Although they are relatively simple to implement, they are more suitable for static data. In contrast, cursor-based pagination is complex but best for changing data as it prevents data inconsistencies. With StepZen, it's straightforward to implement cursor-based pagination for any API.

Learn more by visiting StepZen Docs. Try it out with a free account, and we'd love to get your feedback and answer any questions on our Discord.

Generate a GraphQL API For Amazon RDS PostgreSQL With StepZen

Roy Derks — Thu, 13 Oct 2022 09:16:02 +0000

StepZen is a GraphQL-as-a-Service cloud infrastructure that helps you to build and deploy scalable, secured, and performant GraphQL APIs from different data sources. With StepZen, you can get your GraphQL API up and running from a database (MySQL, PostgreSQL, NoSQL) or an existing REST or GraphQL API.

In this post, you'll learn how to use StepZen with an Amazon RDS database based on PostgreSQL.

About Amazon (AWS) RDS databases

Amazon Web Services Relational Database System (or AWS RDS PostgreSQL) is a cloud-based relational database system that makes it easier to set up, operate, and scale a relational database in the cloud. Amazon RDS databases offer a high availability for PostgreSQL, making them a perfect fit for usage in high-traffic production environments. Next to high availability, you can easily deploy new databases, get backup and recovery options, plus enhanced security as opposed to running a PostgreSQL database on-premise.

There's a huge benefit in using AWS RDS together with StepZen, as both services run in the cloud and are optimized for performance. GraphQL APIs created with StepZen are scaled automatically to meet the traffic demands of your API. So you don't have to worry about your API’s traffic and security because StepZen has got you covered! On the other hand, AWS RDS makes sure your database won't be a bottleneck when you experience increased traffic from your GraphQL API.

This post will show how to generate a GraphQL API for AWS RDS PostgreSQL using StepZen. Let's get started!

Set up AWS RDS Setup: Creating and connecting a PostgreSQL database with Amazon’s Relational Database Service (RDS)

We will learn how to create and connect a PostgreSQL database to a cloud-based database management system. This was normally a daunting task, but it is now a straightforward thing to do, all thanks to AWS.

You can create and deploy six relational databases to Amazon Web Service through their RDS web products. The database engines supported by RDS include MariaDB, Oracle Database, MySQL, SQL Server, Amazon Aurora, and of course PostgreSQL.

Step 1: Sign up for an Amazon Web Services account

Creating an Amazon Web Service account is very easy. All you need to do is go to aws.amazon.com. The landing page of this website is generic, like other sites. All you have to do now is click on "Create AWS account."
Step 2: Create an RDS instance

After creating your AWS account, go to services located in the upper left corner or footer. Click on it and select RDS. After selecting RDS, you’ll be prompted to select a relational database engine. In this case, we’ll be using the PostgreSQL database engine. You’ll also notice a drop-down menu where you can select the database version. Select the most recent version, or at least the second most recent.
Step 3: Configure your Database Instance

At this point, you're expected to give your database instance a name and set a master username and password. The password and username you set here are used for local and cloud database interaction.

After selecting "PostgreSQL" as the database engine, you need to configure the database instance size, availability, and storage. Though it’s always good to make personalized choices, you should leave everything in the default settings at this point in AWS database creation, and this is simply because the best choices have already been ticked by default. Finally, click on "Create Database."

We will have to wait for some time so that AWS can finish setting up our newly created database. This process usually doesn’t take more than 10 minutes. And boom! Our database is ready!

We’re done creating our database. It is now time to connect our cloud database to our local PostgreSQL. We’ll be using pgAdmin 4 as our local PostgreSQL development environment.

Integration of pgAdmin and AWS PostgreSQL

Connecting PostgreSQL databases to AWS is straightforward. All you have to do is get the connection credentials readily available at "view connection details". The only information you require from AWS is the port number, host endpoint, username, and some security group configurations.

Step 1: Copy Login Credentials from "Connection Details".

All the details you need to connect to the new AWS RDS PostgreSQL database are already available after database instance creation. The next thing to do is to click on the security group bar and look for inbound rules. To avoid disrupting the PostgreSQL-AWS connection, click on the Edit inbound rule and select "Anywhere."
Step 2: Download and install pgAdmin or the EDB PostgreSQL Suite

You can download pgAdmin from their official website. The same is true for PostgreSQL from EDB. The setup is basically straightforward, and just click on the installer and wait for the program to finish installing.
Step 3: Launch pgAdmin and connect to AWS database

Launch the already installed pgAdmin like any application. Right-click on the server object in the pgAdmin and click on "create".

Enter the name of your database instance and click on the connection tab. Enter the login credentials from the AWS RDS console and finally click on "save".

Your workspace should have some changes by now and include a schema for the PostgreSQL database.

Let's continue by adding data to this database in the next section.

Adding Data to AWS RDS using pgAdmin

We're almost done setting up the database. It's time to add some data into our AWS RDS database, which we will use to create our GraphQL schema with StepZen. For this, we'll again be using pgAdmin, which we've already set up in the previous section.

You can also use other tools to add data to a PostgreSQL database, for example directly from the command line with psql.

We will use a couple of products as data for our database. Each product has its description, price, quantity, and their unique IDs. To achieve this, we’ll create a table named Products`. With the following columns:

area: The area of our table is Products, since we will be storing product data.
id: This serves our primary key.
description: Which carries the name of our product.
quantity: Which shows the quantity of each product.
price: This column carries the price of each product.

The CSV data below contains the data used in our database columns:

csv "area","id","description","quantity","price" "Product",1,"Rice",20,120 "Product",2,"Bread",400,5 "Product",3,"Oysters",35,50 "Product",4,"Beans",10,3 "Product",5,"Grape",456,23

Adding data to our remote database is the same as with local databases, and all you have to do is to locate the "table" in your workspace.

Click on it and then click on "Create a new table". Create a table name and then click on the column bar. You're going to add your table columns here.

To view and edit table data, just right-click on your table name and select “View and Edit Data.” The image below shows the column and row data we used in our Postgres.

After creating the table data, click "refresh" to synchronize your primary database. This will ensure that all new changes are pushed to AWS.

Generating a GraphQL Schema from AWS RDS

Now that we have our database set up, it’s time to generate a GraphQL schema. We’ll be using StepZen to generate our GraphQL schema. StepZen is a GraphQL API service that allows you to connect to any data source and generate a GraphQL schema from it that you can deploy to the cloud.

To use StepZen, you need to install the CLI. The installation process of StepZen CLI is not a difficult one. All you have to do is to use the following npm commands:

bashnpm install -g stepzen`

Make sure to have Node.js installed on your machine, as it's used as the runtime for the CLI. After installing the CLI, you can generate a GraphQL schema from your AWS RDS database.

Step 1: Create a StepZen account

To use StepZen CLI, you must create an account just like we did during the AWS setup. You can create an account here. Then go to your StepZen dashboard, where you can monitor the APIs you've deployed and access the login details you need for StepZen's CLI.

You can get your username and API key from your My StepZen - Authentication tab. You'll need these credentials to log in to the StepZen CLI.
Step 2: Login in the StepZen CLI

To login to the StepZen CLI, you need to use the following command:

bashstepzen login`

`

This will prompt you to enter your username and API key. After entering the credentials, you'll be logged in to the StepZen CLI.
Step 3: Use StepZen to import AWS RDS PostgreSQL

StepZen has made it simple to import databases from different sources; AWS RDS PostgreSQL is no exception. All you have to do is to use the commands below. The credentials for Amazon RDS PostgreSQL are the same as the ones we used to connect to pgAdmin.

`bash
$ stepzen import postgresql

? What would you like your endpoint to be called? (api/product-list)

Downloading from StepZen...... done

? What is your host?

? What is your database name?

? What is the username?

? What is the password? [hidden]
`

StepZen will automatically create a GraphQL schema for your PostgreSQL database with a set of sample queries and mutations if the process is successful.

If you open the directory created from the above StepZen commands, you're going to see the following files:

postgresql/index.graphql: This file contains the GraphQL schema for your database.
index.graphql: This file contains the index of all GraphQL schemas in case you're using multiple data sources.
config.yaml: This is where our database configuration files are located.
stepzen.config.json: This is where our StepZen endpoint is located. You can also see it on your StepZen dashboard.

Let's deploy these files to the StepZen cloud in the next section.

Deploying the GraphQL Schema to StepZen

So far, we've set up a PostgreSQL database using AWS RDS, seeded it with data, and created a GraphQL schema for this database. This means we're almost done. Deploying the GraphQL API is the last step, and all you have to do is to type the command below.

bashstepzen start`

This will deploy our GraphQL schema to the endpoint in stepzen.config.json. A link will be generated for you at the terminal. The URL for local exploration of your GraphQL API using GraphiQL looks something like:

htmlhttp://localhost:5001/api/product-list`

You can then test your GraphQL API after the link opens. You can also monitor the number of queries and requests made through the endpoint in your StepZen dashboard, the data in the dashboard is updated every day.

The GraphQL schema that we generated from our database has the queries as seen below:

graphql """ These are some examples of queries generated from the schema. Feel free to modify them or add your own. """ type Query { getProductsList: [Products] @dbquery( type: "postgresql" schema: "public" table: "Products" configuration: "postgresql_config" ) getProducts(id: Int!): Products @dbquery( type: "postgresql" schema: "public" table: "Products" configuration: "postgresql_config" )
}
`

We can query our database using the getProductsList and getProducts queries. The getProductsList query returns all the data in the database, while the getProducts query returns a single row of data from the database.

This code below will query for the description of the products in our database:

graphql { getProductsList { description } }

The response will be a JSON response that includes the description of the products in our database. You can also request fields like the price or quantity for every product. From GraphiQL, it will look like the following:

From GraphiQL, you can also explore the GraphQL schema and test out the queries and mutations. You can also use the StepZen GraphQL API to build a frontend application.

Conclusion

This post taught you how to generate a GraphQL API for an AWS RDS PostgreSQL database. We have covered how to set up and connect pgAdmin to AWS RDS PostgreSQL, install StepZen, import data from AWS RDS, and deploy and query StepZen GraphQL API.

Want to learn more about StepZen? Try it out here or ask any question on the Discord here.

Join us for Hacktoberfest 2022 by contributing to StepZen

Roy Derks — Wed, 28 Sep 2022 16:45:26 +0000

Hacktoberfest 2022 is about to start! Join us for the latest edition of Hacktoberfest by contributing to StepZen. We're looking for contributors to help us create new integrations and improve existing ones. Contributors will receive limited StepZen goodies and Hacktoberfest swag.

Hacktoberfest 2022

Hacktoberfest is a celebration of open-source software. It's a month-long event that takes place every October. The goal of Hacktoberfest is to encourage developers to contribute to open-source projects. Hacktoberfest is open to everyone in our global community. You can sign up anytime between September 26 and October 31 via the Hacktoberfest website.

Everyone that signs up for Hacktoberfest here has to make four pull requests (PRs) to public repositories on GitHub (or Gitlab). You can make pull requests to any public repository on GitHub with issues labeled hacktoberfest. Once approved and merged by the repository maintainers, your pull requests count towards your Hacktoberfest goals.

If you complete four pull requests in October, you'll receive a free Hacktoberfest t-shirt and a limited edition Hacktoberfest 2022 sticker pack. You can find more information about Hacktoberfest on the Hacktoberfest website.

Contribute to StepZen

StepZen is participating in Hacktoberfest, and you can contribute by adding a new integration or improving an existing integration in our Examples repository. Every PR to this repository will count towards your Hacktoberfest goals.

In this repository, you'll find two things:

Examples of how to use StepZen to build a GraphQL API by integrating with databases or external APIs.
Usage of a StepZen API in a (frontend) application.

We're looking for contributors to help us create new integrations and improve existing ones. You can find a list of integrations that we're looking for in the issues for the repository, including a list of improvements to existing integrations. But we encourage you also to open a new issue and PR for other integrations.

Next to being eligible for the official Hacktoberfest, we'll ship StepZen goodies to contributors. Read the contributing guidelines before creating a PR.

Keep an eye out for new features and more integrations on our Twitter page and Discord community.

How to Cache GraphQL Requests Using Kong and StepZen

Roy Derks — Thu, 22 Sep 2022 15:52:47 +0000

GraphQL is often used as an API gateway for microservices, but can also play nicely with existing solutions for API gateways. For example using Kong, an API gateway and microservice management platform. As an API Gateway, Kong has many capabilities that you can use to enhance GraphQL APIs. One of those capabilities is adding a proxy cache to the upstream services you add to Kong. But when it comes to caching with GraphQL, there are several caveats you must consider due to the nature of GraphQL. In this post, we will go over the challenges of caching a GraphQL API and how an API gateway can help with this.

Why Use API Caching?

Caching is an important part of any API — you want to ensure that your users get the best response time on their requests as possible. Of course, caching is not a one-size-fits-all solution, and there are a lot of different strategies for different scenarios.

Suppose your API is a high-traffic, critical application. It's going to get hit hard by many users, and you want to make sure it can scale with demand. Caching can help you do that by reducing the load on your servers and improving all users' performance while potentially reducing costs and providing additional security features. Caching with Kong is often applied at the proxy layer, meaning that this proxy will cache requests and serve the response of the last call to an endpoint if this exists in the cache.

GraphQL APIs have their challenges in caching that you need to be aware of before implementing a caching strategy, as you'll learn in the next section.

Challenges of Caching with GraphQL

GraphQL has been getting increasingly popular amongst companies. GraphQL is best described as a query language for APIs. It's declarative, which means you write what you want your data to look like and leave the details of that request up to the server. This is good for us because it makes our code more readable and maintainable by separating concerns into client-side and server-side implementations.

GraphQL APIs can solve challenges like over fetching and under fetching (also called the N+1 problem). But as with any API, a poorly designed GraphQL API can result in some horrendous N+1 issues. Users have control over the response of a GraphQL request by modifying the query they send to the GraphQL API, and they can even make the data nested on multiple levels. While there are certainly ways to alleviate this problem on the backend via the design of the resolvers or caching strategies, what if there was a way to make your GraphQL API blazing fast without changing a single line of code?

StepZen adds caching to queries and mutations that rely on @rest, see here for more information.

By using Kong and GraphQL Proxy Cache Advanced plugin, you totally can! Let's take a look.

Set up caching for GraphQL with Kong

When you're using Kong as an API gateway, it can be used to proxy requests to your upstream services, including GraphQL APIs. With the enterprise plugin GraphQL Proxy Caching Advanced, you can add proxy caching to any GraphQL API. With this plugin, you can enable proxy caching on the GraphQL service, route, or even globally. Let's try this out by adding a GraphQL service to Kong created with StepZen.

With StepZen, you can create GraphQL APIs declaratively by using the CLI or writing GraphQL SDL (Scheme Definition Language). It's a language-agnostic way to create GraphQL as it relies completely on the GraphQL SDL. The only thing you need to get started is an existing data source, for example, a (No)SQL database or a REST API. You can then generate a schema and resolvers for this data source using the CLI or write the connections using GraphQL SDL. The GraphQL schema can then be deployed to the cloud directly from your terminal, with built-in authentication.

Create a GraphQL API using StepZen

To get a GraphQL using StepZen, you can connect your data source or use one of the pre-built examples from Github. In this post, we'll be taking a GraphQL API created on top off a MySQL database from the examples. By cloning this repository to your local machine, you'll get a set of configuration files and .graphql files containing the GraphQL schema. To run the GraphQL API and deploy it to the cloud, you need to be using the StepZen CLI.

You can install the CLI from npm:

`npm i -g stepzen`

After installing the CLI, you can sign-up for a StepZen account to deploy the GraphQL API on a private, secured endpoint. Optionally, you can continue without signing up but bear in mind that the deployed GraphQL endpoint will be public. To start and deploy the GraphQL API, you can run:

`stepzen start`

Running this command will return a deployed endpoint in your terminal (like https://public3b47822a17c9dda6.stepzen.net/api/with-mysql/__graphql). Also, it produces a localhost address that you can use to explore the GraphQL API locally using GraphiQL.

Add a GraphQL Service to Kong

The service you've created in the previous section can now be added to your Kong gateway by using Kong Manager or the Admin API. Let's use the Admin API to add our newly created GraphQL API to Kong, which only requires us to send a few cURL requests. First, we need to add the service, and then a route for this service needs to be added.

You can run the following command to add the GraphQL service and route. Depending on the setup of your Kong gateway, you might need to add authentication headers to your request:

curl -i -X POST \
  --url http://localhost:8001/services/ \
  --data 'name=graphql-service' \
  --data 'url=https://public3b47822a17c9dda6.stepzen.net/api/with-mysql/__graphql'

curl -i -X POST \
  --url http://localhost:8001/services/graphql-service/routes \
  --data 'hosts[]=stepzen.net' \

The GraphQL API has now been added as an upstream service to the Kong gateway, meaning you can already proxy to it. But not before we'll be adding the GraphQL Proxy Caching Advanced plugin to it, which can also be done using a cURL command:

curl -i -X POST \
  --url http://localhost:8001/services/graphql-service/plugins/ \
  --data 'name=graphql-proxy-cache-advanced' \
  --data 'config.strategy=memory'

Using Kong as a proxy for the GraphQL API with the addition of this plugin, all requests are cached automatically at the query level. The default TTL (Time To Live) of the cache is 300 seconds unless you overwrite it (for example 600 seconds) by adding --data' config.cache_ttl=600. In the next section, we'll explore the cache by querying the proxied GraphQL endpoint.

Querying a GraphQL API

The proxied GraphQL API will be available through Kong on your gateway endpoint. When you send a request to it, it will expect to receive a header value with the hostname of the GraphQL. As it is a request to a GraphQL API, keep in mind that all requests should be POST requests with the Content-Type: application/json header and a GraphQL query appended in the body.

To send a request to the GraphQL API, you must first construct a GraphQL query. When you visit the endpoint where the GraphQL API is deployed, you find a GraphiQL interface - an interactive playground to explore the GraphQL API. In this interface, you can find the complete schema, including the queries and possibly other operations the GraphQL API accepts.

In this interface, you can send queries and explore the result and the schema as you see above. To send this same query to the proxied GraphQL API, you can use the following cURL:

curl -i -X POST 'http://localhost:8000/' \
--header 'Host: stepzen.net' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query getCustomerList {\n getCustomerList {\n name\n }\n}","variables":{}}'

This cURL will return both the response result and the response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 445
Connection: keep-alive
X-Cache-Key: 5abfc9adc50491d0a264f1e289f4ab1a
X-Cache-Status: Miss
StepZen-Trace: 410b35b512a622aeffa2c7dd6189cd15
Vary: Origin
Date: Wed, 22 Jun 2022 14:12:23 GMT
Via: kong/2.8.1.0-enterprise-edition
Alt-Svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
X-Kong-Upstream-Latency: 256
X-Kong-Proxy-Latency: 39

{
  "data": {
    "getCustomerList": [
      {
        "name": "Lucas Bill"
      },
      {
        "name": "Mandy Jones"
      },
      …
    ]
  }
}

In the above, the response of the GraphQL API can be seen, which is a list of fake customers with the same data structure as the query we sent to it. Also, the response headers are outputted, and here are two headers that we should focus on: X-Cache-Status and X-Cache-Key. The first header will show if the cache was hit, and the second shows the key of the cached response. To cache the response, Kong will look at the endpoint you send the request to and the contents of the post body - which includes the query and possible query parameters. The GraphQL Proxy Advanced Plugin doesn't cache part of the response if you reuse parts of a GraphQL query in a different request.

On the first request, the value for X-Cache-Status will always be Miss as no cached response is available. However, X-Cache-Key will always have a value as a cache will be created on the request. Thus the value for X-Cache-Key will be the key of the newly created cached response or the existing cache response from a previous request.

Let's make this request again and focus on the values of these two response headers:

X-Cache-Status: Hit
X-Cache-Key: 5abfc9adc50491d0a264f1e289f4ab1a

The second time we hit the proxied GraphQL API endpoint, the cache was hit, and the cache key is still the same value as for the first request. This means the previous request's response has been cached and is now returned. Instead, the cached response was served as the cache status indicated. Unless you change the default TTL of the cache, the cached response stays available for 300 seconds. If you send this same request to the proxied GraphQL API after the TTL expires, the cache status will be Miss.

You can also inspect the cached response directly by sending a request to the GraphQL Proxy Advanced Plugin directly. To get the cached response from the previous request, you can use the following endpoint on the Admin API of your Kong instance. For example:

`curl http://localhost:8001/graphql-proxy-cache-advanced/5abfc9adc50491d0a264f1e289f4ab1a`

This request returns HTTP 200 OK if the cached value exists and HTTP 404 Not Found if it doesn't. Using the Kong Admin API, you can delete a cached response by its key or even purge all cached responses. See the Delete cached entity section in the GraphQL Proxy Cache Advanced documentation for more information on this subject.

Conclusion

This post taught you how to add a GraphQL API to Kong to create a proxied GraphQL endpoint. By adding it to Kong, you don't only get all the features that Kong offers as a proxy service, but you can also implement caching for the GraphQL API. You can do this by installing the GraphQL Proxy Cache Advanced, which is available for Plus and Enterprise instances. With this plugin, you can implement proxy caching for GraphQL APIs, letting you cache the response of any GraphQL request.

Announcing Local Development of StepZen GraphQL APIs with Docker

Roy Derks — Fri, 16 Sep 2022 11:57:45 +0000

Announcement! Everyone can now locally develop GraphQL APIs with Docker. So far only enterprise customers have been able to run StepZen locally, but this option is now available to everyone.

At StepZen we want to make it as simple as possible to create a secure, and performant GraphQL API. Being able to locally develop and run your APIs is vital when you're building a new service, and this latest feature will make that possible.

Using Docker for local development

Running StepZen locally has many benefits. For example, you can run your GraphQL API on your local machine, and connect to your local database. This is useful when you're developing a new GraphQL API, and want to test it locally before deploying it to a public or private cloud.

This new feature is available from the StepZen CLI version 0.21.0 which you can download from npm. With the CLI you can create, run and deploy GraphQL APIs directly from your terminal or command line.

By default the StepZen CLI runs your GraphQL as a managed service on Google Cloud, where your GraphQL API is optimized for performance and security. Or to a private cloud for enterprise customers.

But this same CLI can now also be used to locally run your GraphQL CLI using Docker. Instead of deploying it to a public or private cloud, your local machine will be used to serve a StepZen GraphQL API.

The StepZen service will run in two Docker containers, one container for the introspection service (which introspects the data sources you're connecting to) and another one that runs your GraphQL API. Also, a PostgreSQL database is used to store any metadata that is needed to run an sync your GraphQL API. The setup instructions are available in the StepZen documentation and include a step-by-step guide to get you started. Including the creation of a PostgreSQL database and the installation of Docker.

When you have the Docker container with StepZen running, you can use the CLI for local development in the same way as when running StepZen in the cloud. For example to import a SQL or NoSQL Database, connect to a REST / SOAP API or to use GraphQL Federation. To create a new StepZen project, please continue to the Getting Started section in the documentation.

Next Steps?

We're always looking to improve StepZen, and continue making updates to our product. We deploy new versions of StepZen weekly, so expect new features to be added regularly.