
GraphQL directives are an incredibly powerful aspect of the GraphQL specification, but you may not be aware of them or have had the opportunity to ever use them. This is partly because the GraphQL spec only defines two "required" directives for an API to be spec compliant, and, even then, they aren't necessarily ones you'd encounter on a regular basis. However, GraphQL directives provide extensibility to a GraphQL API and server in a way that makes them incredibly important, especially to tools like [StepZen](https://stepzen.com). In this post, we'll look at what GraphQL directives are, how they are used and some examples of directives in use.

## What Are GraphQL Directives

At a basic level, a GraphQL directive is a way to annotate a GraphQL schema to indicate that the item being annotated needs to be evaluated differently. Yes, that is vague, partly because directives can do a lot of different things depending on where they are applied (we'll look more at some of the possibilities in a moment). They are always preceded by the `@` symbol, making them easy to recognize.

### Types of Directives

There are two types of directives based upon where they are applied:

1. **Schema directives** – A schema directive is applied to the schema in the SDL (schema definition language), so they are executed when the schema is being created. For example, all of StepZen's custom directives fall under this category since they are all applied to the schema and tell StepZen how to generate the API. The spec defines the locations where these can be applied under [Type System Directive locations](https://spec.graphql.org/June2018/#TypeSystemDirectiveLocation).
2. **Operation directives** – These are applied to a query and therefore affect how that query is processed by the resolvers. The spec defines where these can be applied under [Executable Type Directive locations](http://spec.graphql.org/draft/#ExecutableDirectiveLocation).

To better understand the differences between these two types, let's look at the "required" directives [defined in the spec](http://spec.graphql.org/June2018/#sec-Type-System.Directives).

### Required Directives

There are technically three "required" directives for creating a spec-compliant server. I put required in quotes because you definitely can create a GraphQL API server that doesn't implement them, but it just wouldn't technically be fully spec-compliant (if that matters to you).

1. `@include` - This is an operation type directive that can be added to a query to include a field, fragment spread or inline fragment if the supplied argument is true.
2. `@skip` - Similar to the above, this operation type directive can be added to a query to skip this field, fragment spread or inline fragment if the argument is true.
3. `@deprecated` - This is a schema type directive that indicates that a field or enum value has been deprecated in the schema and can supply a reason for the deprecation.

Both `@include` and `@skip` can be included in a query that is being passed to the GraphQL server and will affect how the query is processed, by either skipping or including a part of the query based upon a given argument. However, `@deprecated` would only ever be added to a schema definition.

## Why Should You Care About Directives?

None of the required directives really make a case for why they are important. It's also possible that, as a consumer of GraphQL APIs, you haven't even encountered a directive. The critical thing to know about directives is that they essentially offer a way to extend the GraphQL spec to add new functionality not defined in the spec. What kind of functionality? Well, pretty much anything.

As Leonardo Losoviz states in his excellent article [GraphQL directives are underrated](https://blog.logrocket.com/graphql-directives-are-underrated/):

> Directives are a playground for both GraphQL server implementers and end users alike. GraphQL server implementers can develop features not currently supported by the spec, and users can develop features not yet implemented by the GraphQL server.
>
> Directives’ unregulated nature is a feature, not a bug.

Let's explore some of the uses of directives to see what this can mean in action.

### Examples

The `@computed` directive is a community example of a schema type directive that can help avoid having to create resolvers for values that can be computed from the value of other fields in the schema. The common example is providing a full name field that is comprised of the value of first name plus last name.

```graphql
type User {
  firstName: String
  lastName: String
  fullName: String @computed(value: "$firstName $lastName")
}
```

In this example, the resolver does not need to handle the `fullName` field because the `@computed` directive takes care of that.

StepZen primarily uses GraphQL directives to tell our system how to generate the full schema and resolvers that StepZen deploys on your behalf. Thus, StepZen's custom directives are also all schema type directives.

For example, if you wanted to connect a query to a REST endpoint in a schema on StepZen.

```graphql
type Query {
  getArticles(username: String!): [Article]
    @rest(
      endpoint: "https://dev.to/api/articles?username=$username"
    )
}
```

In this case, `@rest` is a custom directive that can be applied to a query. In the above example, we've supplied only one argument to the directive (`endpoint`). StepZen uses this directive to write the resolver that handles the `getArticles` query so that it can connect this query to data from the supplied REST endpoint. StepZen has a similar directive, `@dbquery`, for connecting a database backend. There are also [community implementations of a similar `@rest` directive](https://github.com/graphql-community/graphql-directive-rest).

> To learn more about how to connect a REST API to StepZen, check out my post "[Turning a REST API into GraphQL Using StepZen](https://stepzen.com/blog/rest-to-graphql)."

## Where to Go From Here

If you're new to GraphQL, seeing directives can be disorienting and confusing, especially since you won't always encounter them. Hopefully this has given you a general understanding of what they are and how they are used. As you can see, they can be quite powerful, but you may not have occassion to use them unless you come across a system that supports them in queries or you are implementing your own GraphQL API, whether via a tool like StepZen or manually writing the code yourself.

If you'd like to learn more about directives, here are some useful resources.

* [GraphQL Directives official spec](http://spec.graphql.org/June2018/#sec-Type-System.Directives)
* [GraphQL.org - Learn Directives](https://graphql.org/learn/queries/#directives)
* [GraphQL directives are underrated](https://blog.logrocket.com/graphql-directives-are-underrated/) by Leonardo Losoviz
* [GraphQL directives documentation](https://www.apollographql.com/docs/apollo-server/schema/directives/) from Apollo Server
* [Schema directives documentation](https://www.graphql-tools.com/docs/schema-directives/) in GraphQL Tools


GraphQL directives are a powerful aspect of the GraphQL spec that you may not even be aware of. They provide extensibility to to a GraphQL API. This post looks at what GraphQL directives are, how they are used and some examples of directives in use.


What You Need to Know About GraphQL Directives


Posting on behalf of [Brian](https://twitter.com/remotesynth/), [Anthony](https://twitter.com/ajcwebdev/),  [Samuel](https://twitter.com/samuelgarretth/), [Lucia](https://twitter.com/CerchieLucia/), [Carlos](https://twitter.com/carloseberhardt/), [Anant](https://twitter.com/jhingran/), and the entire StepZen team.

---
Last week over 150 developers wrapped up a week of building and learning at the [Mintbean](https://mintbean.io/) + [StepZen](stepzen.com) [**QraphQL:Learn 'n' Hack Hackathon**](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333). In this post, we'll take a look at the projects (in alphabetical order) that our *Learn 'n' Hackers* built. You can access a demo for each project and the source code in GitHub via the links below.

We were truly inspired by everyone's energy and creativity. We know that everyone learned a lot about GraphQL. We learned a lot too and we had a blast. We are thrilled to keep working with you on the Mintbean Discord and over on the [StepZen Discord](https://discord.gg/9k2VdPn2FR)

## Bearometric Radio
![bearometric radio](/images/blog/hackathon-bearometric.png)

[The Bearometric Radio](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/6f13c553-b14b-4707-b981-e7eb2cd13a52) web app recommends music to listen to based on the weather. [Will Campbell](https://www.linkedin.com/in/williamkcampbell/) and
[Jay Cammarano](https://www.linkedin.com/in/jay-cammarano/) built their app around a weather-report GraphQL API and a couple of music-related APIs. The app has a React frontend (with a touch of vanilla JS).

## Get a Dog

![dogs API](/images/blog/hackathon-dogs-api.png)
[The Get a Dog](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) web app allows you to select a dog type and returns information and a picture of a dog. [Ethan Wright](https://www.linkedin.com/in/ethan-wright-91a75270/) uses a React frontend and queries a GraphQL API for the [thedogapi](https://www.thedogapi.com/) that he built on StepZen.

## Holidays
![holiday app](/images/blog/hackathon-holiday-app.png)

[The Holidays app](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) calls two REST APIs (calendarific.com and ip-api) combining the responses into a single GraphQL endpoint. The React client queries for data about this year's holidays as if it was queried from a single GraphQL API. [Erica Melo de Carvalho](https://www.linkedin.com/in/erica-melo-de-carvalho/) and [Aamir Bakhtiar](https://www.linkedin.com/in/aamir-bakhtiar-86b3551ba/).

## Eature
![eature app](/images/blog/hackathon-eature.png)

[Stephanie Hou](https://www.linkedin.com/in/houstephanie/?miniProfileUrn=urn%3Ali%3Afs_miniProfile%3AACoAABY8h1ABRwDdMadoTCA2e47E6m0k1R4zxQk) and 
[Michael Fuery](https://www.linkedin.com/in/michaelfuery/) give us [Eature](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/eab19d21-b59e-4e4a-8a0d-7143f1ce2d36) - an app that lets us visualize events recorded by NASA's Earth Observatory Natural Event Tracker (EONET). The team brought a good amount of data together from several APIs to create an informative yet simple UI.

## Kiki's Recipe
![Kiki's Recipes app](/images/blog/hackathon-kikis-recipes.png)

For the [Kiki's Recipe](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) project
[Danny Serrano](https://www.linkedin.com/in/serranodanny/),
[Marjorie Mejia](https://www.linkedin.com/in/marjorie-mejia/), and
[Natalie Rojas](https://www.linkedin.com/in/natalie-o-rojas/) used the following technologies – React, Bootstrap, Spoonacular API, Apollo Client, GraphQL, StepZen, Heroku (deployment) – to build an app that allows us to provide 10 ingredients, hit submit and viola! - we are returned some amazing recipes.

## Lunch Time

For the [Lunch Time](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f4aadf68-5496-4a22-a544-56f925025bd8) app, our developers,
[Kelsey Schroeder](https://www.linkedin.com/in/kelsey-m-schroeder/),
[Leslie Meng](https://www.linkedin.com/in/leslie-meng/), and
[Calvin Lowe](https://www.linkedin.com/in/calvin-lowe/) take a different angle on the food theme. By building a GraphQL endpoint on a couple of Google Sheets data sources, they allow us to determine how much we can afford to pay for lunch today.

## MLB Showdown

![MLB Showdown app](/images/blog/hackathon-mlb-showdown.png)

For the [MLB-Showdown-StepZen](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/63562e68-1a01-4621-9b26-d3b9f94997dc) app,
[John Ratanaprasatporn](https://www.linkedin.com/in/john-ratana-7aa24063/) took his love for the MLB-Showdown card game and re-created it digitally by building a GraphQL API on a REST backend. John used React, React Spring and StepZen in his project.

## React StepZen Comets (Fireballs)
![Fireballs app](/images/blog/hackathon-fireballs.png)

For the [React StepZen Comets](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/68941c26-2b12-42a9-8828-3df18772f226) project,
[David Griffin](https://www.linkedin.com/in/david-griffin-117b0045/) and [Dale Sakamoto](https://www.linkedin.com/in/dalesakamoto/) built a site to track meteors using NASA's JPL Fireballs API. They generate an array of Meteor objects. Users input a location, the app queries the Google Maps API and generates longitude and latitude coordinates. By comparing the coordinates to the array of meteors, the app finds the closest recent meteor strike and returns the meteors impact energy and velocity. In a clever visualization, the app shows us how the comet's speed compares to the fastest man and car.


## Rocket-X
![Rocket X app](/images/blog/hackathon-rocket-x.png)

For the [Rocket-X](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/6681028f-634d-4f5a-9d2e-0d46ecc183c0) app,
[Nara K](https://www.linkedin.com/in/hurricanenara/) and [Lauren Lee](https://www.linkedin.com/in/lauren-hyuna-lee/) created a GraphQL API in StepZen that combined data from two REST APIs, api.spacexdata.com/v4/rockets and api.spacexdata.com/v4/launches, to show us all the rocket launches. They bootstrapped the project with Create React App.


## Running Event Page Creator
![running event page creator](/images/blog/hackathon-running-event.png)

[Jesse Moore's](https://www.linkedin.com/in/jesse-moore-00804030/) [Running Event Page Creator](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/321818e0-b00a-4faf-afe7-b1cf2ab014c8) is a single-page app that dynamically creates event pages using data from multiple tables in an Airtable base. Using StepZen, Jesse combines multiple REST queries into one client-side GraphQL query. The app converts the race name into a readable URL slug, parses a user-provided gpx file route into an interactive map, and user-provided latitude and longitude points into respective markers.


## The Cartoon Character Quiz
![cartoon character quiz](/images/blog/hackathon-cartoon-quiz.png) 

Naomi C. built this [Cartoon Character Quiz](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/abe736f7-4bbf-4f87-b79c-f2447f8a3cd4) using StepZen, GraphQL, and the REST [Last Airbender API](https://github.com/paigeegorry/last-airbender-api). Give it a try - it's addictive!

## SpaceX Launch Dashboard
![SpaceX Dashboard](/images/blog/hackathon-spacex-dashboard.png)

[Seth Mitchell](https://www.linkedin.com/in/sethayottemitchell/) and Steven Larsen built a [SpaceX Launch Dashboard](https://github.com/sethayotte/SpaceX-Launch-Dashboard), .

> "We were able to build a comprehensive and dynamic launch dashboard utilizing SpaceX's API with minimal code using super-cool "materializers" to pare back and condense queries to only necessary response data.
![spacex app tweets](/images/blog/hackathon-spacex-tweets.png)


## The Pointless Dashboard
![The Pointless Dashboard](/images/blog/hackathon-pointless-dashboard.png)

[Nina Jhunjhnuwala](https://www.linkedin.com/in/ninajhunjhnuwala/),
[Jerry Ong](https://www.linkedin.com/in/jerryong89/), and
[Christopher Gitmed](https://www.linkedin.com/in/christopher-gitmed/) treat us to [The Pointless Dashboard](https://mintbean.io/meets/1210c780-f910-4511-aec8-a364420f8333/projects/f89b44e4-1687-4df3-a133-ac46a6de30d3). Well, they had a point! They determined the best way to learn GraphQL was to make the API and do a bunch of API queries. They used React.js and Bootstrap 4 on the frontend. Then StepZen to convert REST APIs into GraphQL endpoints. Then GraphQL to query the APIs and fetch the data necessary to populate the various widgets on the dashboard.

---
The [StepZen team](/about) looks forward to continuing our exploration of GraphQL with you all and can't wait to see what you build next. Hit us up anytime on the [StepZen Discord](https://discord.gg/9k2VdPn2FR).

Huge gratitude to to our friends at [Mintbean](https://mintbean.io/). We look forward to working with you all again. Not yet signed up for StepZen? [Try it free](https://stepzen.com/request-invite).

Along with the mintbean.io team, we wrapped a **GraphQL:Learn 'n Hack Hackathon** last week. Developers had a blast building with GraphQL and we loved working with everybody. Here are some of the projects that developers built.


GraphQL Hackathon: It's a Wrap


# How To Build a GraphQL API Connected to a MySQL Database Using StepZen

GraphQL makes your life easy. As opposed to using a REST paradigm to access your datasource, you don't have to filter out data you don't need.

You ask for what you want:

```graphql

    {
    fruit(id: 1){
        name
        isPoisonous
        }
    }

```

and you get back exactly that.

```graphql
    {
    "fruit": {
        "name": "banana",
        "isPoisonous": false
        }
    }
```

Now, if you add StepZen to the mix, you can query your database in a similar way — and for simple queries, you won't have to write a line of SQL.

You'll also save on the codespace you need to set up your connection. Let's see how.

## Getting Set Up

To follow along with the steps in this post, you'll need to have a database that is deployed to Heroku. If you don't have one, you can follow these instructions to get one set up:

1. Download MySQL workbench [before you start](https://dev.mysql.com/downloads/). You should also have MySQL installed on your machine in order to use the workbench.

2. Sign up for [a Heroku account](https://signup.heroku.com/). It can be on the free tier, but you'll need to add a credit card to your account to use the add-ons that you need (it won't be charged as a part of this tutorial). Once you've done that, you can proceed.

3. Go to your dashboard and click 'New', then 'Create New App'. Type in your app name and hit 'Create App'.

4. Click on the 'Resources' tab and search for 'ClearDB MySQL' under 'Add-ons'. Click on it and select the 'Ignite-Free' plan and then 'Submit Order Form'.

5. Now click 'Settings' and 'Reveal Config Vars'. For the value of `CLEARDB_DATABASE_URL` you should see a string formatted like `mysql://USERNAME:PASSWORD@HOSTNAME/DB_NAME`. You'll use this info for setting up a new connection in your MySQL Workbench in the next few steps.

>NOTE: in the `DB_NAME`, leave off the `?` and everything after it.

### Seeding your database from MySQL Workbench

If you've already got your own database with data in it, then you can follow along with our instructions using it. If you don't have data in your database, you'll need to seed it with data first by following these instructions:

1. Open up MySQL workbench.
* Click the home icon at the top left corner.
* Next to 'MySQL Connections' click the + button, then name your connection whatever you want
* Enter the `USERNAME` and `HOSTNAME` from your heroku account. You can leave the port as it is.
* Click 'Store in Keychain'and add your `PASSWORD`.
* Click 'Test Connection'.  You won't need a default schema.
* Once you hit 'OK' on the notification that your connection was successful, hit 'OK' again.
* Click on your connection to open it.

2. Click the 'schemas' tab on the top left. Double click the name of your schema on the left to make sure it is selected, and copy and paste this code:

```sql
CREATE TABLE `authors` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(45) NOT NULL,
  `isPseudonym` tinyint(4) DEFAULT '0',
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

CREATE TABLE `books` (
  `id` int(11) NOT NULL,
  `name` varchar(45) NOT NULL,
  `originalPublishingDate` date NOT NULL,
  `authorID` int(11) DEFAULT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

INSERT INTO `authors`
VALUES
(1,'Agatha Christie',0),
(2,'Sir Arthur Conan Doyle',0),
(3,'Edgar Allan Poe',0);

INSERT INTO `books`
VALUES
(1,'Murder on the Orient Express','1934-01-01', 1),
(2,'The Mysterious Affair at Styles','1920-10-01', 1),
(3,'The Adventure of the Three Garridebs','1924-10-25', 2),
(4,'The Murders in the Rue Morge','1841-04-04', 3);
```

3. Make sure it is either 1) all selected or 2) not selected at all and click the little lightning bolt under the Query 1 tab. This will run the SQL code that seeds your database.

4. Query the database to verify the seed data was entered:

```sql
SELECT * FROM authors
```

![SQL query response](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3ytpjr9pqtppntjcvv8x.png)


### Set yourself up with StepZen

You'll need a StepZen account. If you don't already have one, you can [request an invite here](https://stepzen.com/request-invite).

### Install StepZen CLI

The StepZen CLI will allow you to easily upload, deploy and test your GraphQL API. It can be installed globally via npm.

```bash
npm install -g stepzen
```

### Login to StepZen account

Before you can deploy to StepZen, the CLI will need your account information, which can be added via the `login` command.

```bash
stepzen login -a [account name]
```

You'll need your account name and admin key, which are accessible via your ["My Account" page](https://my.stepzen.com/account).


## Let's get started on connecting MySQL

First we need to set some configuration. Create a file called `.gitignore` In the same folder as this project, make a file called `config.yaml` Then add `config.yaml` to your .gitignore to keep it from being committed. It's private info! :key:

This is what you'll place in it:

```yaml
configurationset:
  - configuration:
      name: MySQL_config
      dsn: USERNAME:PASSWORD@tcp(HOSTNAME)/DB_NAME
```
What does this code do? It provides StepZen the information it needs to connect to your database.

What's next? Let's dig into writing GraphQL files.

## GraphQL Files

We'll start with `book.graphql`, which is written in GraphQL Schema Definiton Language.

You're going to see some code starting with the `@` symbol. These are [GraphQL directives](https://spec.graphql.org/June2018/#sec-Type-System.Directives). The two directives below are custom directives that the team at StepZen invented.

Notice the `@materializer` directive on the type. When we query `book`, we want to be able to see information on the book's `author` as well, and we're able to do this by using the materializer to query `author` and return the `name`. It will use the `authorID` field to find each `author`.

If you've got different data in different tables, you'll need a type for each table, which fields for the data you want to return from each table. You can use `@materializer` similarly to connect your tables, as well as `@dbquery` to query your database easily.

```graphql
type Book {
  id: ID!
  name: String!
  originalPublishingDate: Date!
  authorID: ID!
  author: Author
  @materializer(
        query: "author"
        arguments: [{ name: "id" field: "authorID"}]
  )
}
type Query {
  book(id: ID!): Book
        @dbquery(type: "mysql", table: "books", configuration: "MySQL_config")
  books(originalPublishingDate: Date!): [Book]
        @dbquery(
            type: "mysql",
            query: "SELECT * FROM books WHERE ? >= DATE '1900-00-00'",
            configuration: "MySQL_config"
        )
}


```

## What's in the query?

The `@dbquery` directive does a lot here. First, it tells StepZen that we're using a database query and that we're using MySQL.

In the first `@dbquery` directive, we only supply a `table` property because the table fields match the properties in our type. StepZen automaticaly assigns the right database field to the right property for us.

In the second directive, we need to customize the data that StepZen gets from the table, so we supply a `query` property. The query we pass, ` SELECT * FROM books WHERE ? >= DATE '1900-00-00` is a custom query that returns only books written in the 1900's and beyond. You can supply any type of query you want here, for example joining two tables together to populate a single type.


## Other Types

In `author.graphql`, we follow a similar pattern. You can write a type for each table in your database like this.

```graphql
type Author {
  id: ID!
  name: String!
  isPseudonym: Boolean!
}
type Query {
  author(id: ID!): Author
        @dbquery(type: "mysql", table: "authors", configuration: "MySQL_config")
  authors(isPseudonym: Boolean!): [Author]
        @dbquery(
            type: "mysql",
            query: "SELECT * FROM authors WHERE isPseudonym = ?",
            configuration: "MySQL_config"
        )
}
```

But how do we tell StepZen that we want to tie these different schema files together?

## Combining the Schema

That's where `index.graphql` comes in:

```graphql
schema @sdl(files: ["author.graphql", "book.graphql"]) {
  query: Query
}
```

This file tells StepZen all of the files to combine to generate your GraphQL schema. And that's the last piece in the puzzle! :fireworks:

## Deploying to StepZen

Upload your config.

```bash
stepzen upload configurationset {{PROJECT_FOLDER_NAME}}/config --file=./config.yaml
```

Upload your schema and deploy to StepZen.

```bash
stepzen upload schema {{PROJECT_FOLDER_NAME}}/schema --dir=. &&
stepzen deploy {{PROJECT_FOLDER_NAME}}/api --schema={{PROJECT_FOLDER_NAME}}/schema --configurationsets={{PROJECT_FOLDER_NAME}}/config
```

## The StepZen GraphiQL Query Editor

In your terminal you can now you run:

```bash
stepzen start
```

Name your endpoint, and then StepZen will open up a GraphiQL query editor connected to your database!

So, if you had a database with a book table as well as an author table, pasting this code into your query editor:

```graphql
{
  book(id: 1) {
    id
    author {
      id
    }
  }
}
```

Would get you a result like:

![GraphQL query response](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/puq3k1sgjczsq4i0tv8o.png)

## Where to go from here
If you have questions about MySQL and StepZen, feel free to [consult the `@dbquery` docs](https://my.stepzen.com/docs/build-a-graphql-endpoint/dbquery). If you want to download the code from this blog post, [check out our sample schema](https://github.com/stepzen-samples/stepzen-mysql).


Here, we give you an in-depth look at how you can easily use StepZen to connect your MySQL database to a GraphQL API.


How to Build a GraphQL API Connected to A MySQL Database Using StepZen

A step-by-step guide demonstrating how to build a GraphQL API that pulls from multiple REST endpoints using StepZen.


Turning a REST API into GraphQL Using StepZen




The A in Jamstack stands for **APIs**. These are the first- or third-party APIs that are accessed at build-time using the static site generators, or on the client using JavaScript. They enable developers to hydrate both static and dynamic content with data from various backend sources. We'll explore how the APIs can truly be the first-class citizen in the Jamstack ecosystem - one that developers leverage effectively.

> *APIs are the sweet dynamics that sweeten a Jamstack application to be more than a “static site.” Web developers can use relatively simple HTTP calls to endpoints maintained and scaled by other providers, thereby abstracting away all of their server-side concerns*. ~[Jamstack Attack! Static Sites, Dynamic APIs, and a Killer DX](https://blog.readme.com/jamstack-static-sites-dynamic-apis-killer-dx/)

Developers use APIs and other direct access methods to get the data they need to build and deploy static Jamstack apps and sites. For example, for an eCommerce site you may get product information from Contentful, price information from an API connected to a MySQL database, and product reviews from MongoDB. 

APIs are often used on the client when you want to access dynamic content from the browser. For example, you may have an API that determines the location of your users and therefore you might connect with IP-API (a popular API for determining the locations based on IP address). You may want to tailor your messages or offers based on the weather conditions, and so might connect with OpenWeatherMap’s or the AccuWeather API. You may want the latest, updated inventory, which might be different than the last snapshot of inventory at the time of the last static build. 

![Static and Dynamic Build](/images/blog/static-dynamic-build.png)

APIs are not just the standard but a powerful way for developers to fetch and combine data during static and dynamic builds. We believe that the potential of APIs in Jamstack applications is fully realized when APIs are easy to build and run and can help developers seamlessly harmonize multiple data sources. Let’s look at some of the considerations. 

## No Two APIs are the Same

There are lots of APIs, and each behaves differently. There are different syntax, authorizations, protocols, and kinds of responses. Many APIs are well-documented, and many are not. Beyond discovering the data and its shape, writing the logic to handle it, and other design and build-time considerations, there are run-time concerns that compound the complexity. For example, if you want to call an API from a browser you need to protect the key for that API because you do not want the key to leak into the browser. You must also ensure that the query being executed by the browser is not modified in the browser. For example, say that you have an API that returns available items for sale in a specific month - you want to avoid somebody manipulating the month parameter in the browser. Suddenly they can find out what products will be available for sale next month - potentially leaking competitive information. 

So what do you do? You write a lambda or other serverless function, then deploy and maintain it to take care of the API in question. Then the key and queries for the second API also need to be protected. So you write and deploy another lambda function. And on and on for every additional backend. 

Furthermore, you’ll want to effectively monitor backends and know about response and API changes, API key invalidity, performance degradations. You’ll need to scale to optimize your applications and route around errors, effectively and efficiently handle protocol translations, design caching, handle API keys, access control, and manage rate limits and SLAs effectively. You often need to stitch APIs together, and create logic like “If something happens, call this API, otherwise call this API.” 

So you’re writing, deploying, and maintaining more and more complex code. All this results in a decent amount of work that you must do to build, manage, and secure your APIs and apps. 

![Lambda Functions](/images/blog/lambda-functions-complexity.png)


See [How to Secure API Routes for Jamstack Sites](/blog/how-to-secure-api-routes-for-jamstack-sites) for a discussion on making asynchronous API calls in the browser straightforward, and the considerations for authentication, sharing and protecting API keys, restricting what users can do with your API, and more.

## GraphQL: An API of APIs

GraphQL is a natural API of APIs. It allows for different backend data sources and different ways of connecting those backends to be unified in the context of a single GraphQL endpoint. Therefore you can fetch a customer's information, their orders, and the delivery status of those orders all with one GraphQL API. This is one of the big reasons we chose to adopt GraphQL for StepZen.

![API of APIs](/images/blog/graphql-api-of-apis.png)

To fully leverage its power to abstract the complexity of backend APIs away, StepZen makes it easy to set up a GraphQL endpoint to query all your data and avoid the complications of myriad and varied backends. You don't need to be a GraphQL expert, build a GraphQL server, or understand resolvers. You can abstract away any backend - SQL and NoSQL databases, REST and GraphQL APIs, and more - and easily access all the backend data you need.

![As-a-Service](/images/blog/as-a-service-attributes.png)


The GraphQL API you build on StepZen runs on StepZen - meaning that you build and manage zero infrastructure. We ensure that API keys are stored safely, manage access control, monitor the backends for performance, parallelize the execution, and ensure that your API is always-on so that the customers of your Jamstack application are happy. Even as you design and build your GraphQL API, you can test and iterate it locally with a built-in continuous deployment process.

## Summary

We believe that you as a developer have to worry about a lot of things and therefore we strive to make it easy for you to get a GraphQL endpoint up and running. Because you build sites and apps that center on static assets and enable both static and dynamic interaction through APIs, we believe that the **A** in Jamstack is increasingly [best served](https://stepzen.com/blog/why-graphql/) by GraphQL for frontend and full-stack developers alike. With StepZen, you can safely call all the APIs you use for your static assets or the dynamic experience. There are no keys to manage, no infrastructure to run or maintain.

## Where to go from here

Check out the [demo section of the Jamstack-SF meetup video](https://youtu.be/GnCjbXqLV-o?t=615) where we used a simple application that shows all the orders for a customer and their delivery status to demo how the dynamic and statically built data is assembled to power the experience. You’ll see how to select a GraphQL schema (pre-configured with a connection to a backend) from our [API templates](/developers/api-templates) GitHub repository, combine it with GraphQL snippets from a private repository, and deploy the unified GraphQL endpoint that you can query to deliver a static and dynamic experience for your Jamstack site.

Not yet signed up for StepZen? Try it free here https://stepzen.com/request-invite.  We continue to add to our [API templates](/developers/api-templates) ecosystem so that you can grab a pre-built GraphQL API and have your endpoint up and running in minutes. If there's one you'd like to have or an extension to an existing one, we'd [love to hear your ideas](mailto:feedback@stepzen.com). 



APIs are a powerful way to fetch and combine data during static and dynamic builds. We believe that the potential of APIs in Jamstack applications is fully realized when APIs are easy to build and run and help developers seamlessly harmonize multiple data sources.


Realizing the Potential of the API in Jamstack

In our previous article, [Exploring JavaScript Client Libraries for GraphQL](https://stepzen.com/blog/javascript-graphql-libraries), we examined a variety of different GraphQL clients. In this article we will build a React frontend from scratch and focus on integrating Apollo Client.

The client will query a GraphQL API created from the JSONPlaceholder API. We are able to use the [`@rest` directive](https://stepzen.com/blog/how-to-connect-any-rest-backend) to easily translate the JSONPlaceholder API into a GraphQL schema.

![05-unordered-list-of-users](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6667k39b37vmhz2xokwc.png)

You can find all of the code at the [following repo](https://github.com/stepzen-samples/stepzen-react-tutorial).

## 1. Project Setup

We will not use a CLI tool like `create-react-app` to setup our project. Instead we will create all of our files and directories from scratch.

### Create root directory and initialize `package.json`

Our project will be called **`stepzen-react-tutorial`**.

```bash
mkdir stepzen-react-tutorial
cd stepzen-react-tutorial
npm init -y
```

### Add necessary dependencies

```bash
npm i @apollo/react-hooks apollo-boost graphql react react-dom react-scripts
```

Our dependencies will include the following React packages:
* `react` - Contains only the functionality necessary to define components
* `react-dom` - Entry point to the DOM
* `react-scripts` - Scripts and configuration used by [CRA](https://github.com/facebook/create-react-app)

And the following GraphQL and Apollo packages:
* `@apollo/react-hooks` - Common hooks for queries, mutations, and subscriptions
* `apollo-boost` - Pre-configured defaults for Apollo Client
* `graphql` - JavaScript reference implementation for GraphQL

### Add scripts to `package.json`

```json
"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
},
```

* `npm start` - Runs the app in the development mode on `http://localhost:3000`
* `npm test` - Launches the test runner in interactive watch mode
* `npm run build` - Builds the app for production to the `build` folder
* `npm run eject` - Removes the single build dependency from your project and exports configuration files and dependencies into your project as dependencies in `package.json`.

### Add browserslist to `package.json`

```json
"browserslist": {
  "production": [
    ">0.2%",
    "not dead",
    "not op_mini all"
  ],
  "development": [
    "last 1 chrome version",
    "last 1 firefox version",
    "last 1 safari version"
  ]
},
```

Your entire `package.json` should look something like this:

```json
{
  "name": "stepzen-react-tutorial",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "keywords": [],
  "author": "",
  "description": "",
  "dependencies": {
    "@apollo/react-hooks": "^4.0.0",
    "apollo-boost": "^0.4.9",
    "graphql": "^15.5.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-scripts": "^4.0.3"
  }
}
```

## 2. Setup React App

To setup our React frontend create directories for `src`, `src/pages`, and `public`.

```bash
mkdir src src/pages public
```

Create an `index.js` file for our root component, an `index.html` file to load the root component, and a `HomePage` component.

```bash
touch src/index.js src/pages/HomePage.js public/index.html
```

### Create a home page with a title

```javascript
// src/pages/HomePage.js

export default function HomePage() {
  return (
    <>
      <h1>StepZen React Tutorial</h1>
    </>
  )
}
```

### Create root component to render the HomePage component

```javascript
// src/index.js

import React from "react"
import { render } from "react-dom"
import HomePage from "./pages/HomePage"

render(
  <React.StrictMode>
    <HomePage />
  </React.StrictMode>,
  document.getElementById("root")
)
```

### Create html boilerplate with root div

Our `index.html` file includes a simple boilerplate with a root `<div>` to load in our application.

```html


<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1"
    />
    <meta
      name="theme-color"
      content="#000000"
    />
    <meta
      name="description"
      content="How to use Apollo Client to Connect a React Frontend to a GraphQL API"
    />

    <title>React + StepZen App</title>
  </head>
  
  <body>
    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>

    <div id="root"></div>
    
  </body>
</html>
```

Start the development server on `localhost:3000` with the following command:

```bash
npm start
```

![01-index-stepzen-react-tutorial](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8kgkskweraeninudvgru.png)

### Create a Users component

The `Users` component will fetch user data from the [JSONPlaceholder API](https://jsonplaceholder.typicode.com).

```bash
mkdir src/components
touch src/components/Users.js
```

We will need to create our backend before we can fetch any data. For now just include a placeholder title for Users.

```javascript
// src/components/Users.js

export default function Users() {
  return (
    <>
      <h2>Users</h2>
    </>
  )
}
```

Import the `Users` component into `HomePage.js` and return `<Users />`.

```javascript
// src/pages/HomePage.js

import Users from "../components/Users"

export default function HomePage() {
  return (
    <>
      <h1>StepZen React Tutorial</h1>
      <Users />
    </>
  )
}
```

Return to the browser to see the Users title displayed beneath the initial title.

![02-import-users-component](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2clw8xkphk7z694ze4pk.png)

## 3. Setup GraphQL API

To setup our StepZen API create a `stepzen` directory containing a `schema` directory.

```bash
mkdir stepzen stepzen/schema
```

Create an `index.graphql` file for our `schema` and a `users.graphql` file for our `User` type and `Query` type.

```bash
touch stepzen/schema/users.graphql stepzen/index.graphql
```

### index.graphql defines all files making up the GraphQL schema

Every StepZen project requires an `index.graphql` that ties together all of our schemas. For this example we just have the `users.graphql` file included in our `@sdl` directive. The `@sdl` directive is a StepZen directive that specifies the list of files to assemble.

```graphql
# stepzen/index.graphql

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

The `User` type includes an `id` for each `User` and information about the `User` such as their `name` and `email`.

```graphql
# stepzen/schema/users.graphql

type User {
  id: ID!
  name: String!
  username: String!
  email: String!
  phone: String!
  website: String!
}

type Query {
  getUsers: [User]
    @rest(
      endpoint:"https://jsonplaceholder.typicode.com/users"
    )
}
```

For our `Query` we just have a single query called `getUsers` that returns an array of `User` objects. The `@rest` directive accepts the `endpoint` from JSONPlaceholder.

### Deploy API

The `stepzen start` command uploads and deploys your API automatically.

```bash
stepzen start
```

It will ask you to include a name with the format `folder/name`. This is the destination you specify for your endpoint. I named my endpoint `stepzen-react/users`.

A browser window with a GraphiQL query editor can be used to query your new endpoint on `localhost:5000`. Enter the following query to test your endpoint:

```graphql
query getUsers {
  getUsers {
    id
    name
  }
}
```

![03-graphql-api-explorer](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i7bbyjnbkgb05u1i6w75.png)

### Set environment variables

This also deployed our API to `https://username.stepzen.net/stepzen-react/users/__graphql`. We will use this endpoint for our environment variables. Create a `.env` file along with a `.gitignore` file.

```bash
touch .env .gitignore
```

Include `.env` and `node_modules` in your `.gitignore` file to prevent them from being included if we push the project to a public GitHub repository.

```
node_modules
.env
```

In `.env` set:
* Your StepZen API key to `REACT_APP_STEPZEN_API_KEY`
* The endpoint with your username provided by `stepzen start` to `REACT_APP_STEPZEN_ENDPOINT`

```
REACT_APP_STEPZEN_API_KEY=<YOUR_API_KEY_HERE>
REACT_APP_STEPZEN_ENDPOINT=<YOUR_ENDPOINT_HERE>
```

## 4. Setup Apollo Client

There are many different ways to make GraphQL requests as described in Brian's [previously mentioned article](https://stepzen.com/blog/javascript-graphql-libraries). We will use Apollo Client since it is familiar to many React developers, but future articles will explore alternative implementations.

### Create `utils` directory and `client.js` file

```bash
mkdir src/utils
touch src/utils/client.js
```

Import `ApolloClient` and instantiate a new `client` instance. Set your API key with an authorization header. Set your endpoint to `uri`.

```javascript
// src/utils/client.js

import ApolloClient from "apollo-boost"

const {
  REACT_APP_STEPZEN_API_KEY,
  REACT_APP_STEPZEN_ENDPOINT
} = process.env

export const client = new ApolloClient({
  headers: {
    Authorization: `Apikey ${REACT_APP_STEPZEN_API_KEY}`,
  },
  uri: REACT_APP_STEPZEN_ENDPOINT,
})
```

### Wrap `HomePage` with `ApolloProvider`

Return to `index.js` and import `ApolloProvider` and `client` from the `utils` directory. Wrap the `HomePage` component with `ApolloProvider` and pass the `client` prop with our environment variables to the provider.

```javascript
// src/index.js

import React from "react"
import { render } from "react-dom"
import { ApolloProvider } from "@apollo/react-hooks"
import { client } from "./utils/client"
import HomePage from "./pages/HomePage"

render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <HomePage />
    </ApolloProvider>
  </React.StrictMode>,
  document.getElementById("root")
)
```

### Create `queries` directory and `getUsers.js` file

```bash
mkdir src/queries
touch src/queries/getUsers.js
```

Import `gql` and initialize `GET_USERS_QUERY` with a `query` called `getUsers`. This query returns the `id` and `name` of the users.

```javascript
// src/queries/getUsers.js

import { gql } from "graphql-tag"

export const GET_USERS_QUERY = gql`
  query getUsers {
    getUsers {
      id
      name
    }
  }
`
```

### Pass `GET_USERS_QUERY` into `useQuery`

Return to the `Users` component and import the `useQuery` hook and `GET_USERS_QUERY` from `getUsers.js`.

```javascript
// src/components/Users.js

import { useQuery } from "@apollo/react-hooks"
import { GET_USERS_QUERY } from "../queries/getUsers.js"
```

To perform the query, pass `GET_USERS_QUERY` into the `useQuery` hook.

```javascript
// src/components/Users.js

export default function Users() {
  const {
    data,
    loading,
    error
  } = useQuery(GET_USERS_QUERY)
}
```

We have three possible results from our query.
* Check `loading` and display loading message if `true`.
* Check `error` and display error message if `true`.
* If `data` was received successfully set the response to `users`.

```javascript
// src/components/Users.js

export default function Users() {
  const {
    data,
    loading,
    error
  } = useQuery(GET_USERS_QUERY)

  const users = data?.getUsers
  
  if (loading) return <p>Almost there...</p>
  if (error) return <p>{error.message}</p>
}
```

The `JSON.stringify()` method converts a JavaScript object or value to a JSON string, optionally replacing values if a replacer function is specified. The value of `null` is provided so all properties of the object are included in the resulting JSON string.

```javascript
// src/components/Users.js

  return (
    <>
      <h2>Users</h2>
      <pre>
        {JSON.stringify(users, null, "  ")}
      </pre>
    </>
  )
```

Here is our complete component.

```javascript
// src/components/Users.js

import { useQuery } from "@apollo/react-hooks"
import { GET_USERS_QUERY } from "../queries/getUsers.js"

export default function Users() {
  const {
    data,
    loading,
    error
  } = useQuery(GET_USERS_QUERY)

  const users = data?.getUsers
  
  if (loading) return <p>Almost there...</p>
  if (error) return <p>{error.message}</p>
  
  return (
    <>
      <h2>Users</h2>
      <pre>
        {JSON.stringify(users, null, "  ")}
      </pre>
    </>
  )
}
```

![04-fetch-users-from-jsonplaceholder](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xw3dvkovbdbikjxrride.png)

### Map over `users` array

To display a list of each user we can map over the `users` array. This will return:
* An unordered list of each `user` with the user's `id` set to the `key` property
* Each user's `name` set to a list item

```javascript
return (
  <>
    <h2>Users</h2>

    {users.map(user => (
      <ul key={user.id}>
        <li>
          {user.name}
        </li>
      </ul>
    ))}
  </>
)
```

![05-unordered-list-of-users](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6667k39b37vmhz2xokwc.png)

## Next Steps

We have now seen how to setup our React frontend with Apollo Client to query a GraphQL API deployed to StepZen. With this foundation we could continue building out the project with other libraries such as [React Router](https://github.com/ReactTraining/react-router) for linking between pages, [Next.js](https://github.com/vercel/next.js/) for server-side rendering, or [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss) for styling.

However, we could not deploy our application in its current state because our client has access to our API keys. We would need to deploy a [secure API route](https://stepzen.com/blog/how-to-secure-api-routes-for-jamstack-sites) with a function containing our keys. This can be easily accomplished with frameworks such as RedwoodJS as we will see in future articles. This is because it includes an API side auto-configured out of the box to deploy a GraphQL handler to AWS Lambda.

You can find more example repositories at [StepZen Samples](http://github.com/stepzen-samples). If you're not already part of the private alpha, you can request an invitation [here](https://www.stepzen.com/request-invite).

How to build a React frontend from scratch and query a GraphQL API with Apollo Client


How to use Apollo Client to Connect a React Frontend to a GraphQL API




With GraphQL, you can package and integrate all of your data and APIs behind a well-understood and easy-to-use model. As a GraphQL consumer, you can do the things that you want and avoid the things that you do not want to deal with. For example, when consuming a GraphQL API, you write less code to perform frontend functions, fetch less data (and so lower your costs), experience faster load times, avoid version control pain, and much more.

However, one of the really hard things that still needs to be done is building and running a server to host your API. Choosing to own and operate that GraphQL service is not trivial.

Software as a Service (SaaS) is a hot topic. As the adoption of [cloud](https://www.oreilly.com/radar/cloud-adoption-in-2020/) computing increases, it is largely developers who are driving a shift to cloud and SaaS as solutions to their day-to-day operational issues. From evangelizing iterative design-develop-deploy and agile development methodologies to championing DevOps as a solution to the need for speed in deployments, they are driving the adoption of cloud and SaaS in companies big and small.

But what are developers considering when deciding if they should run their GraphQL API or leverage a SaaS service?  Questions they ask include:

- Can I effectively monitor backends and know about response changes, API changes, API key invalidity, performance degradations?
- Can I scale to optimize my applications and route around errors?
- How effectively and efficiently can I handle structure and protocol translations?
- Do I know how to design caching and make the best tradeoffs between performance and accuracy?
- Can I handle API keys, access control, and managing rate limits and SLAs effectively?
- Can I write and maintain the code for every additional backend that requires new retry logic, error handling logic, caching logic, throttling logic, API key invalidation, response change validation?

In [Why You Shouldn’t Host Your Own GraphQL API](https://thenewstack.io/why-you-shouldnt-host-your-own-graphql-endpoint/), originally published on *The New Stack*, we explored some considerations that developers should keep in mind when deciding between hosting their GraphQL API or choosing a service to do so. See the full article here. [![The New Stack](/media/blog/TNS-for-SZ-repost.png)](https://thenewstack.io/why-you-shouldnt-host-your-own-graphql-endpoint/)







What does a developer need to think through when deciding whether to build, own, and operate a GraphQL API service?


Key Considerations for Hosting Your GraphQL API


This Valentine's Day, don't forget about your BFF. Sure, your BFF may make your life difficult sometimes, but you still need your BFF. No, I'm not talking about your best friend, I'm talking about the BFF architectural pattern. What's BFF? Let's start with a quick summary.

Back in 2015, Phil Calçado [introduced an architectural pattern](https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html) called Backends for Frontends or BFF that had been used at SoundCloud. That same year [Sam Newman defined the pattern](https://samnewman.io/patterns/architectural/bff/) as well.

The BFF pattern grew out of the need to support multiple user interfaces with differing needs, particularly mobile interfaces that had a number of constraints. The monolithic API had become a bottleneck to development and couldn't always serve the needs of the multiple user interfaces easily. So, rather than have each frontend call a single monolithic API backend, each frontend would implement their own API layer that would leverage an application service layer that then called the underlying microservices. This BFF would be maintained by the frontend application team, thus freeing them of the constraints of waiting on changes to the underlying API to iterate on the UI, while also allowing them to refine and structure the API to meet the specific needs of their UI. For example, the mobile UI might require less data than a desktop UI and reducing the payload of an API call could improve the performance of the mobile app.

![BFF pattern illustrated](/images/blog/sc-bff-6.png)
_Source: [The Back-end for Front-end Pattern (BFF)](https://philcalcado.com/2015/09/18/the_back_end_for_front_end_pattern_bff.html)

## What Does BFF Have To Do With Jamstack?

This pattern might not seem entirely relevant to the Jamstack, which frequently relies heavily upon leveraging specialized microservices along with third-party services and APIs. Especially for complex applications, the Jamstack approach can result in some complications:

* Frequently, to use an API within the frontend UI, an intermediary layer needs to be created to protect API key access and limit what parts of the underlying API can be called and from where. This is usually built as a serverless function, which hides the key and exposes specific API functionality. (For a look at how you can secure these endpoints, [read our recent blog post](https://stepzen.com/blog/how-to-secure-api-routes-for-jamstack-sites).)
* Combining multiple microservices, third-party services and APIs can become incredibly complex and hard to maintain. Thus, the intermediary layer can become a place where the various microservice and API calls are combined into a format that is easily consumed by the frontend.

As you can see, while the code may exist in one or more serverless functions, in the scenario I laid out across the two bullet points, we've effectively created a BFF for the Jamstack app. This is something that Jay Freestone spoke about in his recent [Front-end predictions for 2021]([Front-end predictions for 2021](https://www.browserlondon.com/blog/2021/01/04/front-end-predictions-2021/)):

> Over the last few years, the widespread use of micro-services has necessitated patterns such as Backend For Frontend (BFF), which introduces an intermediary between each client and the APIs which service it.
>
> This is particularly relevant in 2021 given the current interest in the JAMStack, which, at its most complex, suffers under the weight of its service dependencies. The answer to ‘how do I federate my APIs’ will be, amusingly: build one.

Now, I personally take Jay Freestone's critiques of Jamstack with a grain of salt. He's been very open about [being a Jamstack skeptic](https://www.browserlondon.com/blog/2020/04/20/issues-with-jamstack-you-might-need-backend/), even if his criticisms seem to reflect a very narrow (and overly Netlify-centric) view of the Jamstack ecosystem. That being said, he's right that this BFF pattern can often apply to the Jamstack and it presents a number of problems in that they can be difficult to build and maintain.

## Does GraphQL Solve the BFF Problem?

As [Bowei Han](https://medium.com/frontend-at-scale/frontend-architectural-patterns-backend-for-frontend-29679aba886c) notes, two of the key benefits of the BFF pattern are the ability to adjust payload size and request frequency reduction while also providing a single resource server for the frontend to call. GraphQL offers advantages over RESTful APIs that would seem to address these issues:

* **The ability to get only the data you need.** A GraphQL query allows you to request only the data you need for your frontend, unlike REST, which sends the entire payload regardless of whether it is needed. For example, if I only need a user's name to display, I can request and receive only that single piece of data.
* **The ability to get all the data you need in a single request.** There's no need to call multiple endpoints and stitch together the data within a GraphQL API because it allows you to request all the data you require across all the available types in in a single query. For example, I don't need to call the user endpoint to get user data and then the orders endpoint to get their orders. I can instead get a user with their orders in a single call.
* **GraphQL provides a single resource server to call.** Unlike REST, there aren't multiple endpoints but a single GraphQL endpoint. There are even tools such as [schema stitching](https://www.graphql-tools.com/docs/schema-stitching/) or [federation](https://www.apollographql.com/docs/federation/) available to combine multiple GraphQL endpoints.

But GraphQL doesn't directly solve the traditional BFF issue nor the "Jamstack BFF." As Phil Calçado mentions in "[Some thoughts on GraphQL vs. BFF](https://philcalcado.com/2019/07/12/some_thoughts_graphql_bff.html)":

> The defining characteristic of a BFF is that the API used by a client application is part of said application, owned by the same team that owns it, and it is not meant to be used by any other applications or clients.

He explains:

> The first friction point is that it is hard for me to believe that you can combine the needs of many different applications, owned by different teams, with different users and use cases, in a single schema.

By nature, the GraphQL API isn't specific to the needs of the frontend application consuming it and we can end up with some of the same difficulties that the BFF pattern was trying solve such as the difficulty iterating on an API that has to serve multiple frontends. Or, as Andy Roberts put it in "[The Evolution of GraphQL at Scale](https://www.apollographql.com/blog/the-evolution-of-graphql-at-scale/)":

> The more teams there are making changes to it, the harder it is to release change, and, before you know it, the dream becomes a nightmare and our monolithic GraphQL API becomes a hated beast.

The solution he recommends is to make a GraphQL schema per experience, essentially mirroring the BFF pattern, and leveraging tools like Apollo Federation to combine multiple schemas as needed per experience to reduce code duplication. The issue, of course, is that neither creating and maintaining multiple GraphQL APIs nor using federation is trivial. Plus, for the Jamstack developer, we also haven't necessarily negated the need for the intermediary layer to authenticate with the GraphQL API and pass through queries.

## Towards Solving This Problem for the Jamstack

We've given these issues a lot of thought at [StepZen](https://stepzen.com), particularly as they relate to the Jamstack. We believe in the benefits of adopting GraphQL to reduce unecessary payload size, reduce the number of requests needed to get data, and provide a single endpoint for your application data. But we also realize this can come with a number of burdens, particularly for the frontend developer.

The biggest problem is that it is time consuming and difficult to spin up new GraphQL APIs, so the idea that you could create one specific to a frontend can be a major burden. It's also not necessarily common for a frontend team to have the expertise needed to build GraphQL APIs. Plus, having to still create the intermediary layer to handle things like keys and access control only increases this burden.

We're not the only company who sees these problems and is tackling them, but we think we have a unique solution to them that makes it easy to spin up new GraphQL APIs, even while combining multiple backend sources (including databases and APIs). This allows frontend developers to create the API they need, even stitching together disparate sources of data. We're also working on solutions to address the need for the intermediary layer for handling keys, so that you'll be able to call your GraphQL API directly from the frontend without writing a serverless function to manage keys and access.

In the end, the BFF pattern solves real problems for developers, but it comes with burdens. Rather than revert to the monolith, if we can mitigate or eliminate those burdens, we can get the benefit of BFF without the pain, and learn to love our BFF again.


Let's explore the BFF pattern, how it applies to Jamstack applications and how to make it easier to implement.


Learn To Love Your Jamstack BFF


If you want to interact with a GraphQL API via your frontend web application, you have a ton of options. [GraphQL.org](https://graphql.org/) currently lists [11 client libraries](https://graphql.org/code/#javascript-client) for JavaScript and, of course, you can [use plain old JavaScript](https://stepzen.com/blog/consume-graphql-in-javascript). In this post, I'll review some of the options for GraphQL client libraries in JavaScript and some of the features that make each of them unique.

The sample code for this post can be [found here](https://github.com/remotesynth/graphql-client-libs). It features the same basic Next.js site built using each of these libraries. While it only covers the basic features of making a GraphQL API request, it can illustrate some of the differences of how each one of these libraries is used. (Note: to run the samples locally, you'll need to create a `.env` file and define a `GITHUB_API_TOKEN` with a personal access token that you can [generate here](https://github.com/settings/tokens)).

## GraphQL Request

[GraphQL Request](https://github.com/prisma-labs/graphql-request) is a library created and maintained by Prisma Labs. I'm choosing to start with this library because it is intentionally designed to be the "minimal", meaning it doesn't include a lot of extra functionality that you'll find in some of the other clients. Basically, GraphQL Request gives you only what you need to easily send and receive GraphQL queries and mutations in the browser or in Node and intentionally little more. This does make GraphQL Request very lightweight and perhaps all you need in many cases.

Let's look at a couple of simple examples. To perform a basic query, all you need to do is npm install and then import graphql-request:

```javascript
import { request, gql } from 'graphql-request';
```

Next, you just pass your API URL and the GraphQL query you want to execute.

```javascript
const query = gql`
  {
    continents {
      name
      code
    }
  }
`;
const results = await request('https://countries.trevorblades.com/', query);
```
To pass a variable, it's just a matter of providing a variables argument as well containing the JSON with the variables:

```javascript
const query = gql`
  query getContinent($code: ID!) {
    continent(code: $code) {
      name
      countries {
        name
      }
    }
  }
`;
const variables = {
  code: code,
};
const results = await request(
  'https://countries.trevorblades.com/',
  query,
  variables
);
```
If you need to pass authorization headers to the GraphQL API, you can instantiate the `GraphQLClient` with the endpoint URL and header variables. Once this is done, you can call the `request()` method on that client.

```javascript
const graphQLClient = new GraphQLClient('https://api.github.com/graphql', {
headers: {
    authorization: 'bearer ' + process.env.GITHUB_API_TOKEN,
},
});
const query = gql`
{
    viewer {
    name
    twitterUsername
    bio
    }
}
`;
const results = await graphQLClient.request(query);
```
Mutations using GraphQL Request are essentially a combination of these three items (i.e. the query with variables and an authorization header). GraphQL Request does have a few other minor features, including support for [file uploads](https://github.com/prisma-labs/graphql-request#file-upload) that you can read about in the [documentation](https://github.com/prisma-labs/graphql-request)

## Apollo Client

Apollo Client is created by Apollo and is the most popular GraphQL client library available. While it can obviously do all of the basics like querying, mutations, variables and such, it doubles as a state management library. You can use Apollo Client to manage local state irrespective of whether you have a GraphQL API to connect to or not. However, the real power comes with the ability to cache the state that you retrieve from the remote API and combine that with additional local application state. All of this is built with React in mind, so, while you don't have to use React, Apollo Client integrates easily with it.

Honestly, there's too much to Apollo Client to cover in great detail here, but let's go over some of the basics of querying. Once you have npm installed Apollo Client, you'll need to import three modules in order to make a basic query.

```javascript
import { gql, ApolloClient, InMemoryCache } from '@apollo/client';
```

The `InMemoryCache` allows you to configure and control Apollo Client's caching strategies. This is particularly useful if you are pulling data on the client. Apollo Client will use the cache wherever it finds that a query has not changed, meaning you will be able to serve responses much faster than reretrieving results over the network. In my example, I'm actually loading content from an API that is being passed via Next.js' `getStaticProps()` method. Since this passes data at build-time, the caching strategy isn't really relevant, but it is still required, so we'll just use the defaults.

```javascript
const client = new ApolloClient({
  uri: 'https://countries.trevorblades.com/',
  cache: new InMemoryCache(),
});
const results = await client.query({
  query: gql`
    {
      continents {
        name
        code
      }
    }
  `,
});
```

Passing variables is pretty straightforward and just a matter of adding the variables key to the `query()` call.

```javascript
const results = await client.query({
  query: gql`
    query getContinent($code: ID!) {
      continent(code: $code) {
        name
        countries {
          name
        }
      }
    }
  `,
  variables: {
    code: code,
  },
});
```

Apollo Client allows for a lot of fine-grained control over the HTTP calls you make using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), including adding authorization via a [Context Link](https://www.apollographql.com/docs/react/api/link/apollo-link-context/). However, for our simple purposes, passing a credentials via a standard request.

```javascript
const client = new ApolloClient({
  uri: 'https://api.github.com/graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: 'bearer ' + process.env.GITHUB_API_TOKEN,
  },
});
```

These basics really don't do Apollo Client justice as, if you want just the core querying features, you can just use GraphQL Request. Since Apollo Client is built with React in mind, many of its key features are geared towards building React single page applications (SPAs). For instance, it comes with a lot of built-in features and components that allow you to directly hydrate your frontend with new data via a GraphQL API using React Hooks. You can also maintain local state that includes both data returned from your GraphQL APIs as well as any other state management. This is powerful enough that I've seen articles arguing for dropping Redux in favor of Apollo Client. To get the full scope of capabilities, check out the [Apollo Client documentation](https://www.apollographql.com/docs/react/).

## Urql

Urql seems to sit somewhere in between GraphQL Request and Apollo Client, having more features and capabilities than the former but fewer than the latter, which makes it much more lightweight than Apollo Client. For example, it does include a highly-configurable caching layer similar to Apollo Client, but it does not include local state management. It also has integrations for theReact, Svelte and Vue frameworks built-in (there's also a [package for Next.js](https://www.npmjs.com/package/next-urql)). If you're looking for a feature-by-feature comparison with Apollo Client, they have one [here](https://formidable.com/open-source/urql/docs/comparison/).

Let's look at doing the basics with Urql here as well. Keep in mind that this sample pulls all its data during build-time, so the framework-specific hooks don't really apply. Instead, we'll just use Urql for simple querying, starting with a basic query. First, we need to import the proper modules.

```javascript
import { createClient } from 'urql';
```

Next, we create the client and the query and then pass that to the client's `query()` method.

```javascript
const client = createClient({
  url: 'https://countries.trevorblades.com/',
});
const query = `
  {
    continents {
      name
      code
    }
  }
`;
const results = await client.query(query).toPromise();
```

You'll note that because we are using async/await, we need to convert the stream that query returns into a JavaScript promise.

Passing variable is pretty much what you'd expect — just add them to the query call.

```javascript
const query = `
  query getContinent($code: ID!) {
    continent(code: $code) {
      name
      countries {
        name
      }
    }
  }
`;
const variables = {
  code: code,
};
const results = await client.query(query, variables).toPromise();
```

To make a request with an authorization, we need to use the `fetchOptions` parameter when calling `createClient()` and pass in an object containing our authorization header.

```javascript
const client = createClient({
  url: 'https://api.github.com/graphql',
  fetchOptions: {
    headers: { authorization: 'bearer ' + process.env.GITHUB_API_TOKEN },
  },
});
```

As with Apollo Client, there's a lot more available within Urql than we can cover here including modules to support server-side rendering (SSR), advanced authentication, retrying operations and caching. To learn more [check the documentation](https://formidable.com/open-source/urql/docs/).

## Connecting to StepZen

Of course, [StepZen](https://stepzen.com) is all about creating GraphQL backends that you can use on your frontend projects. Once you've created an API using StepZen, you'll need to call it using an authenticated Request with your StepZen API key. Here are a few examples of setting it up. (Note that these assume a `.env` file that defines `STEPZEN_API_KEY`)

### GraphQL Request

```javascript
const graphQLClient = new GraphQLClient('https://account-name.stepzen.net/folder-name/api-name/__graphql', {
headers: {
    authorization: 'Apikey ' + process.env.STEPZEN_API_KEY,
},
});
```

### Apollo Client

```javascript
const client = new ApolloClient({
  uri: 'https://account-name.stepzen.net/folder-name/api-name/__graphql',
  cache: new InMemoryCache(),
  headers: {
    authorization: 'Apikey ' + process.env.STEPZEN_API_KEY,
  },
});
```

### Urql

```javascript
const client = createClient({
  url: 'https://account-name.stepzen.net/folder-name/api-name/__graphql',
  fetchOptions: {
    headers: { authorization: 'Apikey ' + process.env.STEPZEN_API_KEY },
  },
});
```

## Which One Should I Use?

You may be wondering, which of these is the right one to use for my project? The answer, perhaps unsurprisingly, is: it depends. However, here are some guidelines for making the choice:

* If you are primarily looking for convenience methods for querying a GraphQL API, but have no need for things like caching, framework integration, or state management, then GraphQL Request offers an easy to use and lightweight solution. For example, in my case, I was querying for a Jamstack application where the data was being integrated at build-time, so none of these features are really relevant for this (even though my example uses the React-based Next.js framework).
* If you are integrating with a framework like React, Vue or Svelte or you want to add in a cache for client-side API calls but you don't necessarily need the full state management solutions that Apollo Client provides, then go with Urql for something more lightweight.
* If you need the most comprehensive solution, including the state management, or you want the deepest integration with React, then Apollo Client is a good choice.

Of course, there are a bunch of other libraries beyond the ones that I discussed here. Check out [this list on GraphQL.org](https://graphql.org/code/#javascript-client) for a more complete list.


Exploring three popular GraphQL JavaScript client libraries that you can use to connect to a GraphQL API in the browser or in Node.js.


Exploring JavaScript Client Libraries for GraphQL


Much has been written in the past few years about REST and GraphQL - indeed REST *versus* GraphQL! Which is better? Is REST dead? What’s the big deal about GraphQL anyway? GraphQL discussions today are reminiscent of the REST debates of a decade ago. Pragmatic versus dogmatic REST anyone? This blog is not that!

Rather it is an example of how developers can leverage two great technologies to simplify and accelerate how they build modern apps and experiences. StepZen just released the capability to make it easy for developers to configure any REST API as the backend data source for their GraphQL endpoint. This lets you GraphQL-enable existing REST backends, and tie together multiple backends into one API accessible at a single endpoint.

## GraphQL for Frontend and Backend Developers

Frontend developers are adopting GraphQL as the way to get data from backends. The [2020 State of JavaScript survey](https://2020.stateofjs.com/en-US/technologies/datalayer/graphql), for example, reports that almost 90% of respondents have used GraphQL, or want to learn more about it, up from barely 50% in 2016. Many of the developers we’ve interacted with are building web apps with the Jamstack, and GraphQL is increasingly a part of that conversation. For example, [Gatsby](https://www.gatsbyjs.com/), [RedwoodJS](https://redwoodjs.com/), and [Gridsome](https://gridsome.org/docs/data-layer/) data layers are all built on GraphQL.

Here at StepZen, we believe that [GraphQL makes the job of the backend developer easier](/blog/why-graphql) as well. It is with an eye to supporting both the frontend and backend developer experience that we land on GraphQL as the choice for a universal API - an API that abstracts all the backends away and the developer just asks for the data she wants.

## But Where’s the Data?

The data that developers need mostly reside in one or more API services and databases. Let’s take a look at the API backend landscape — we'll save databases for another day!

REST turned 20 in 2020. With two decades of APIs designed and built on REST, it's no wonder that there are hundreds of thousands of REST-based APIs powering an even greater number of applications. Programmable Web boasts almost 24,000 APIs in its API directory. About a third of them are REST APIs. And those are just the “public” APIs - the tip of the [iceberg](https://www.programmableweb.com/news/private-api-iceberg/2011/11/03)! With an average of 168 new APIs added monthly, the tip of the Programmable Web [iceberg](https://www.programmableweb.com/news/private-api-iceberg/2011/11/03) has grown[ 6 fold](https://www.programmableweb.com/news/apis-show-faster-growth-rate-2019-previous-years/research/2019/07/17) in just over a decade, and shows no signs of slowing down.

REST APIs have become the de facto standard for companies deploying APIs and launching developer platforms. As we speak with frontend and full-stack developers about their projects, it is therefore no surprise to hear that much of the data they need is available via API backends -- mostly REST — some good, some not so good, some downright ugly.

## Getting Data From a REST Service Using StepZen’s @rest

Whether the data for the GraphQL API you build on StepZen is from databases, APIs, CMSs, or other backends, our goal is to connect and assemble it to deliver the right response reliably. Given the continuing growth of the body of REST APIs, and their importance as data sources for modern applications, we went to work to make connecting REST APIs easy. Let’s take a look at how StepZen’s @rest directive makes that so.

As Anant describes in [this video](https://www.stepzen.com/developers/videos/build-endpoint), the core work of creating a GraphQL endpoint in StepZen is done by writing the schema file (in the form of a *Schema Definition Language* (SDL) file). In three steps, you write the schema that describes your GraphQL endpoint.

1. **Define** an interface and queries for a type that the front-end application will query. This could be a customer type, an order type, a ticket, whatever.
2. **Connect** backends by creating one or more concrete types in support of the interface type. The concrete types represent the backends that will provide data to the interface. When your backend is REST you use the directives `@rest` to tell StepZen how to access and process the backends.
3. **Link** types, as needed, for the interfaces and backends you configured (using the `@materializer` directive).

<img src="/media/blog/define-connect-link.png" alt="define-connect-link" style="zoom:67%;" />

## Anatomy of a Schema: A GraphQL API with a REST Backend

In [a recent blog post](https://www.stepzen.com/blog/build-your-first-graphql-api), Brian described how to build your first GraphQL endpoint in StepZen, so we’ll not cover the same ground here. Instead, let’s look at an example of the SDL file in StepZen that defines a Customer interface, a query for the type, and how to connect to a REST service using the @rest directive (steps 1 and 2 above).

> *If you’re logged in to your StepZen account, you can access the [documentation](https://my.stepzen.com) that fully describes how to connect a REST service using @rest and more. If you don’t have an account yet, you can sign up for the [StepZen alpha](https://stepzen.com/request-invite). It is free to use and you’ll get your own sandbox account to explore StepZen capabilities.*

Here’s our example schema (SDL) file:

```javascript
interface Customer {
    id: ID!
    name: String!
    email: String!
}
type CustomerUsingRest implements Customer {}
type Query {
    customerById (id: ID!): Customer
    customerByIdUsingRest(id: ID!): CustomerUsingRest
    @supplies(query: "customerById")
    @rest (endpoint: "https://customer-more-complex.stepzen.com/customers/$id", resultroot: "data",
        setters: [{field: "name", path: "customername"},
                  {field: "email", path: "customeremail"}])
}
```

Let’s break it down:

- The file defines the interface (`Customer`) and queries for our `CustomerUsingRest` type.
- We implement the `Customer` interface as a concrete type (`CustomerUsingRest`) to connect the backend.
- We implement the query on the concrete implementation and connect it to the REST API backend.
- Let's break down the query `CustomerByIdUsingRest`:
  - `CustomerByIdUsingRest` supplies data to our `customerById` query and, as such, has the same arguments as that query. However, the query returns an instance of `CustomerUsingRest` (our concrete implementation) rather than `Customer`.
  - The `@supplies` directive tells StepZen which query this fulfills. In this case, we're specifying that this query is supplying data to the `customerById` query.
  - The `@rest` directive tells StepZen that this query will be fulfilled by a query to a REST endpoint - in our example, this REST API: `https://samples.apis.stepzen.com/simplecustomer/1`

Note the four parameters typical in an `@rest` call.

- **endpoint** - the URL you want to call. All parameters of the query this @rest is attached to are available to you to construct the URL. You use $ to construct them.
- **resultroot** is the root where all the data you need for the concrete type that the call feeds into. Default is the root of JSON.
- **setters** is the optional renaming of fields from JSON into the fields of the concrete type. Only fields that need to be remapped need to be specified, otherwise StepZen makes good default assumptions.
- **configuration** is the optional configuration information to pass down into headers, and/or information that you do not want to write in your SDL.

Let’s look at the **configuration** parameter.

As you saw in [Building Your First GraphQL API Using StepZen ](https://www.stepzen.com/blog/build-your-first-graphql-api)in order to connect a custom backend, you create a config.yaml file in your project directory. It specifies the information StepZen needs to connect to the backend. Let’s say, in this example, we want to connect Customer with the authenticated REST backend:

`https://samples.apis.stepzen.com/auth/morecomplexcustomer/1`, using `-H Authorization: Bearer XXXXX`

To set this value for StepZen, you’d create a `config.yaml` file in your project as follows:

```javascript
configurationset:
  - configuration:
      name: stepzen_customer
      Authorization: Bearer XXXXX

```

and therefore, our example schema file contains the  `configuration: "stepzen_customer"` parameter.

And so, by using the `@rest` directive in your schema definition, you can GraphQL-enable REST backends and easily connect REST services as the data sources in your GraphQL endpoint.

## Summary

As frontend developers adopt GraphQL as the way to get data from backends, and because we believe that GraphQL can also make the job of the backend developer easier, we chose it for building "One API for all Your Data." However, since Roy Fielding’s famous [Chapter 5](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), and with more than 20 years of APIs designed and built on REST, across many industries and sectors, it's no surprise that REST APIs are some of the more common backends that a developer must connect to get the data she needs. So we wanted to make it easy to connect any backend REST API when building your single GraphQL endpoint.

We hope you’ll check out our [latest release](http://stepzen.com/request-invite) and the StepZen [documentation](https://my.stepzen.com) for the details of connecting a REST API using the `@rest` directive. You can not only GraphQL-enable your existing REST backends, but also tie together multiple backends into a single API accessible at a single endpoint.


We've added new capabilities that make it easy to connect your GraphQL endpoint with any REST data source, using the @rest directive.


How to Connect Your GraphQL API with any REST Backend


While not explicitly connected with each other, GraphQL and the Jamstack seemingly have had histories that seem to be intertwined in large part because both have been linked in many ways to the rise of the React framework. While created in 2012 by Facebook, GraphQL was officially open sourced in 2015, two years after React, which also came from Facebook. GraphQL (as you may already know) is a query language for building and querying APIs. As of 2018, the GraphQL spec is maintained by the independent [GraphQL Foundation](https://foundation.graphql.org/).

Meanwhile the Jamstack is largely an architecture or methodology around building web sites that centers on static assets that allow for dynamic interaction through the use of JavaScript and APIs. The architecture was around for a few years prior but, in an effort led by Netlify, it was officially given the Jamstack name in 2016. While it does use APIs, it does not explicitly prescribe what sort of APIs, so there's no overarching connection to GraphQL. However, in 2015 Kyle Matthews released a React-based static site generator named [Gatsby](https://www.gatsbyjs.com/) that was built upon React and tightly integrated with GraphQL for its entire data layer. Although Gatsby is no longer the only static site generator to use GraphQL by default, Gatsby's fast-rising popularity ultimately linked GraphQL with the broader concept of the Jamstack.

Let's explore a couple of popular Jamstack tools and how they use GraphQL.

## Gatsby

[![Gatsby](/images/blog/gatsby.png)](https://gatsbyjs.com)

Let's start with Gatsby as, to my knowledge, it was the first to explicitly tie GraphQL with the creation of Jamstack applications (though, in truth, Jamstack was not yet a word when Gatsby first came out). Every Gatsby site comes with a data layer. Ideally all the data for a site flows through this layer, including file-based content stored in Markdown, JSON or YAML files as well as external GraphQL APIs or APIs and services connected via a plugin. And this data layer is entirely built upon GraphQL.

![Gatsby's embedded GraphiQL](/images/blog/graphiql_gatsby.png)

Although it [isn't a requirement](https://www.gatsbyjs.com/docs/how-to/querying-data/using-gatsby-without-graphql/) that your Gatsby site uses GraphQL to get its data, doing so comes with a [number of benefits](https://www.gatsbyjs.com/docs/why-gatsby-uses-graphql/) such that you are strongly encouraged to do so. Thus, every time you run `gatsby develop`, Gatsby not only spins up your site (typically at `localhost:8000`) but also spins up the GraphQL API for your site (typically accessible via `http://localhost:8000/___graphql` using the embedded GraphiQL editor).

For example, if you were to use Gatsby's [blog starter](https://github.com/gatsbyjs/gatsby-starter-blog), it uses file-based content in the form of Markdown files for each blog post that are stored in the `/content/blog` folder. It then uses the `gatsby-source-filesystem` plugin to add the frontmatter and content of these files into Gatsby's GraphQL data layer and then retrieves them using a query along the lines of:

```graphql
{
  allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
      nodes {
        excerpt
        fields {
          slug
        }
        frontmatter {
          date(formatString: "MMMM DD, YYYY")
          title
          description
        }
      }
    }
}
```

To learn more about how to use GraphQL in Gatsby, check out the [GraphQL API documentation](https://www.gatsbyjs.com/docs/reference/graphql-data-layer/graphql-api/).

## Gridsome

[![Gridsome](/images/blog/gridsome.png)](https://gridsome.org)

Gridsome shares a lot of feature and philosophical similarities to Gatsby, but it is built using the Vue framework. For instance, Gridsome focuses on being a static site generator, unlike some other framework-based tools that offer both server-side rendering (SSR) and static pre-rendering (SSG). It also has a strong first-party and community plugin ecosystem. And, it also has a data layer that is built upon GraphQL that you can explore using the built-in GraphQL Playground.

![Gridsome GraphQL](/images/blog/graphql_gridsome.png)

The GraphQL data layer is where all the data about a site is added by default, including site metadata and pages. Gridsome provides built in tools to add in data that is coming from outside sources. For instance, you can use `api.loadSource` hook in a `gridsome.server.js` in conjunction with Gridsome's [Data Store API](https://gridsome.org/docs/data-store-api/) to add data from an external API. Any data I add to the data layer via the Data Store API is immediately queryable using GraphQL.

For example, imagine I wanted to pull in all of the blog posts that I'd written on DEV (note that this example uses the unauthenticated endpoint to get a user's public posts). Here's my `gridsome.server.js`:

```javascript
const axios = require('axios');

module.exports = function(api) {
  api.loadSource(async (actions) => {
    const posts = await axios.get(
      'https://dev.to/api/articles?username=remotesynth'
    );

    const collection = actions.addCollection('DevPosts');

    for (const post of posts.data) {
      collection.addNode(post);
    }
  });
};

```

And now I can query the API using the generated `AllDevPosts` query:

```graphql
query {
  allDevPosts {
  	edges {
      node {
        title
        description
        url
      }
    }
  }
}
```

To learn more about how Gridsome uses GraphQL, check the [GraphQL data layer documentation](https://gridsome.org/docs/data-layer/).

## GraphQL in Other Jamstack Tools

Another more recent addition to the list of Jamstack static site generators that use GraphQL as their data layer is [RedwoodJS](https://redwoodjs.com/), which brings a Rails-like approach to building what they call "full stack Jamstack." RedwoodJS puts its data layer in what it calls [cells](https://redwoodjs.com/docs/cells) that must contain a GraphQL query.

Of course, GraphQL can be used in just about any other static site generator that is capable of parsing the JSON response (which is pretty much any of them). I only cover these specifically because they are built upon GraphQL as a core capability. However, Jamstack is more than just static site generators. The other key ingredient is APIs and services and GraphQL plays a large part in that as well. For instance, there are common tools that make GraphQL a foundational part of their offering like [Fauna](https://fauna.com/), which provides a data API for a Jamstack site, or [GraphCMS](https://graphcms.com/), which is a headless CMS built upon a GraphQL API.

At [StepZen](https://stepzen.com), we're also focused on the Jamstack and GraphQL by building tools that will make it easy for developers to combine all their backends into a single API endpoint built on GraphQL. We believe that GraphQL offers unique capabilities that make it ideal for a serverless, "Jamstack-ready" API layer that avoids the need for boilerplate functions. Because of this, we think GraphQL will increasingly become an integral part of the API layer of Jamstack - that the A in Jamstack will increasingly stand for GraphQL.


A look at the intertwined evolution of the Jamstack and GraphQL and how popular Jamstack tools are built upon a GraphQL foundation.


GraphQL and the Jamstack


One of the problems facing developers today is that we are getting data from a disparate variety of sources. One application may get data from a variety of internal RESTful APIs, internal databases and even third-party APIs and services. It is rare that all these pieces know about each other - even across internal APIs - so it falls upon the developer to write complex and often fragile code to bring all these systems together.

[StepZen](https://stepzen.com) offers a platform that solves these problems by enabling developers to bring all the pieces of their backend together into a single API enabled via GraphQL. Curious? In this tutorial, we'll walk through the steps to building your first GraphQL API using StepZen. In this case, we'll use a MySQL backend, but be aware that StepZen supports multiple backend connectors.

Before we can get started, the first thing you'll need to do, of course, is get access to the [StepZen private alpha](https://stepzen.com/request-invite). It is free to use and we'll work to get you access quickly. Once you have access, there is a ton of [documentation](https://my.stepzen.com/) available to learn how the system works, but we'll walk through the key steps here.

## What We'll Build

We're going to build a very simple GraphQL API with *critically important* data about Scooby Doo characters and episodes. A GraphQL API is based around types, and our API will consist of two types: character and episode. For the sake of example, these are very simple (as we'll see in a moment).

The actual data will come from a MySQL database. I am hosting my MySQL database via Heroku, but where you choose to host the database isn't important provided that it is accessible by StepZen's service (if you'd like to use Heroku, the steps to do this are available in [the StepZen documentation](https://my.stepzen.com/docs/reference/setup-stepzen#setupyourownmysql(optional))).

### Creating the Database

Let's create our MySQL data by creating the two very simple tables and populating them with a little bit of data.

```SQL
CREATE TABLE `characters` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(45) NOT NULL,
  `isMonster` tinyint(4) DEFAULT '0',
  `episodeID` int(11) DEFAULT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

CREATE TABLE `episodes` (
  `id` int(11) NOT NULL,
  `name` varchar(45) NOT NULL,
  `originalAirDate` date NOT NULL,
  PRIMARY KEY (`ID`),
  UNIQUE KEY `ID_UNIQUE` (`ID`)
);

INSERT INTO `characters` VALUES (1,'Scooby Doo',0,0),(2,'Daphne Blake',0,0),(3,'Shaggy Rogers',0,0),(4,'Fred Jones',0,0),(5,'Velma Dinkley',0,0),(6,'Black Knight',1,1),(7,'Ghost of Captain Cutler',1,2),(8,'Phantom',1,3),(9,'Miner Forty-Niner',1,4);

INSERT INTO `episodes` VALUES (1,'What a Night for a Knight','1969-09-13'),(2,'A Clue for Scooby Doo','1969-09-20'),(3,'Hassle in the Castle','1969-09-27'),(4,'Mine Your Own Business','1969-10-04');
```
Ok. Now that we have our data, we can move on to the fun part - building the API.

## Getting Set Up With StepZen

Once you have your private alpha account on StepZen, the first thing you'll want to do is install the StepZen CLI.

```bash
npm install -g stepzen
```

Next, we'll need to connect the CLI to your StepZen account. The details you need can be found on the [my account page](https://my.stepzen.com/account). You'll need both the account name and the admin key. Run the following, replacing `[account name]` with the account from your [my account page](https://my.stepzen.com/account).

```bash
stepzen login -a [account name]
```

You'll then be prompted to enter your admin key. Don't worry, you'll only have to do this once.

## Creating the API

Let's start by creating a new project folder for our Scooby Doo API.

```bash
mkdir scooby-api
cd scooby-api
```
Next, we'll create the files for our GraphQL types: Character and Episode. These are written using standard [GraphQL SDL (Schema Definition Language)](https://www.prisma.io/blog/graphql-sdl-schema-definition-language-6755bcb9ce51) that StepZen uses these to generate your full GraphQL schema. Before I start writing code, there are some key concepts to understand when building your API with StepZen:

* The fields and their associated types are written as a GraphQL interface. This is done so that you can have multiple implementations of a type in cases where the data may be supplied by multiple different backends. For example, a shipping type that uses both a FedEx and a UPS data source.
* A type is a concrete implementation of an interface and is typically used to define how the the connection to a backend where data is retrieved.

There's more to it than that, which you can [read about in the docs](https://www.my.stepzen.com), but, for now, let's get to writing some code. First, let's create a file to define the interface and queries for our Character type in a file named `character.graphql`:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}

type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
}
```
Our character type has four fields. We've also defined two queries. One will get a single character based upon an ID and the other will get a list of characters based upon whether that character is a monster or not. Let's create a similar file called `episode.graphql` for our Episode type:

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type Query {
  episode(id: ID!): Episode
}
```

In this case, we have just three fields and only a single query defined to get an episode by its ID.

### Tying The Schema Together

We need one more file in order to tie the different files in our schema together for StepZen: `index.graphql`. It lists all the files in the schema that StepZen will use to assemble the GraphQL API. In this case, we only have two - `character.graphql` and `episode.graphql` - so our `index.graphql` will look like the following:

```graphql
schema @sdl(files: ["character.graphql", "episode.graphql"]) {
  query: Query
}
```
We're ready to upload our schema to StepZen. From the command line, be sure you are in your project's root folder and run:

```bash
stepzen upload schema scoobyapi/schema --dir=.
```

This will push the code to StepZen and perform some validation on it. The `scoobyapi/schema` represents the folder name and schema name for this schema. I can use whatever I want here, but it is important to note that whetever value I place here will be needed in later commands (also note that the folders are scoped to your user account, so you don't need to worry about name conflicts with other users).  You can specify a different directory than the one you are in by changing the `--dir` flag.

You should get a resonse like the following:

```bash
Uploading...
Successfully uploaded the schema
```
Ok. Let's go ahead and deploy this to StepZen. You'll want to deploy this to the same folder (i.e. `scoobyapi`) as the schema, though you can name it whatever like (I used `scoobydoo`). Supply the schema folder and name from the upload (`scoobyapi/schema`).

```bash
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema
```

You should receive a response like the following, though your endpoint will be different:

```bash
Deploying...
Redeployment successful!
Your endpoint can be found at: https://biggs.stepzen.net/scoobyapi/scoobydoo/__graphql
```

Using a tool like [GraphQL Playground](https://github.com/graphql/graphql-playground), we can now inspect our API using the URL provided. Open GraphQL Playground and enter the URL. You'll need to click HTTP Headers and provide the API Key from your [my account page](https://my.stepzen.com/account) as an authorization header in the following format:

```json
{
    "Authorization": "Apikey MYAPIKEY"
}
```

Now, if you click on docs, you should see the types associated with your new API.

![API docs in GraphQL Playground](/images/blog/api-docs.png)

However, if you try to run a query like:

```graphql
{
  character(id:1) {
    name
  }
}
```

...you'll get a null response:

```json
{
  "data": {
    "character": null
  }
}
```

This is because we haven't told our API where to get the data from yet. Let's do that.

### Connecting Mock Data

Connecting our API to mock data is as simple as adding a custom `@mock` [GraphQL directive](https://graphql.org/learn/queries/#directives) to our interfaces. For example, here is our updated `character.graphql`:

```graphql
interface Character @mock {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}

type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
}
```

Let's also add the same `@mock` directive to our `episode.graphql` and then upload and deploy:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema
```

Now if we run the same query from earlier, we'll get mock data in the result:

```json
{
  "data": {
    "character": {
      "name": "In vel mi sit amet augue congue elementum"
    }
  }
}
```

## Connecting MySQL

Ok, mock data is great - and easy - but let's populate our API with some real data!

### Creating a Configuration

The first step to connecting a custom backend is to create our own configuration set to supply to StepZen that contains the connection information needed to connect to the MySQL database. Create a file called `config.yaml` within your project directory. You'll need your MySQL database username, password, hostname and database name. Assuming you have all that information handy, create a MySQL configuration in the following format (replacing the values in the `dsn` for your connection information):

```yaml
configurationset:
  - configuration:
      name: MySQL_config
      dsn: username:password@tcp(hostname)/databasename
```

Next you'll need to upload this configuration to StepZen. The best practice would be to place it in the same folder as the schema. You can name it whatever you like (I named mine just `config`). Keep this folder and name handy though as you'll need them again when we deploy.

```bash
stepzen upload configurationset scoobyapi/config --file=./config.yaml
```

You should receive a response like the following:

```bash
Uploading...
Successfully uploaded the configurationset
```
Now that StepZen knows how to connect to our database, we can modify the types to implement that backend.

### Creating Concrete Types

First of all, let's remove the `@mock` directive from each type as we're now going to populate it with real data. Next, we need to implement each interface as a concrete type to connect the backend. We can do this in separate files, but our types are simple enough here that, to keep things easy, we'll just add this to the current `character.graphql` and `episode.graphql`.

Let's look at the Episode type first. First we need to create the concrete implementation. In this case,  though we can leave it empty as to will only contain the same fields contained within the interface. I've named mine `EpisodeBackend` but you can name it whatever you like.

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type EpisodeBackend implements Episode {}
type Query {
  episode(id: ID!): Episode
}
```
Now that we have the concrete implementation, we can implement the query and connect it to MySQL. Here's the full complete code

```graphql
interface Episode {
  id: ID!
  name: String!
  originalAirDate: Date!
}
type EpisodeBackend implements Episode {}
type Query {
  episode(id: ID!): Episode
  episodeFromBackend(id: ID!): EpisodeBackend
    @supplies(query: "episode")
    @dbquery(type: "mysql", table: "episodes", configuration: "MySQL_config")
}
```

Let's break down the query (`episodeFromBackend`) piece by piece so that it makes sense:

* `episodeFromBackend` will supply data to our `episode` query and, as such, has the same arguments as that query. However, the query returns an instance of `EpisodeBakend` (our concrete implementation) rather than `Episode`.
* The `@supplies` directive is what tells StepZen which query this will fulfill. In this case, we're specifying that this query is supplying data to the `episode` query (i.e. the query directly above it).
* The `@dbquery` directive tells StepZen that this query will be fulfilled by a database query. We're supplying a type of `mysql` in order to use the MySQL connectors in StepZen and telling it to use the table `episodes` and the configuration `MySQL_config` that we defined earlier in our configuration set. Since our table fields match the fields in our type, we don't need to supply anything else - StepZen is smart enough to figure out the proper query to construct to get the data.

Let's go ahead and upload and deploy these updates to our schema. Notice that our deploy command now specifies the configuration we uploaded earlier via the `--condigurationsets` flag.

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```

Let's go ahead and test this out by running a query in GraphQL Playground:

```graphql
{
  episode(id:1) {
    name
  }
}
```

This should return the real data we populated at the beginning of this tutorial:

```json
{
  "data": {
    "episode": {
      "name": "What a Night for a Knight"
    }
  }
}
```

Let's do the same for the Character type, leaving out implementing the `characters` query for now:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}
type CharacterBackend implements Character {}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
}
```

Upload and deploy it:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```

And finally, query it:

```graphql
{
  character(id:1) {
    name
  }
}
```

The result should be:

```json
{
  "data": {
    "character": {
      "name": "Scooby Doo"
    }
  }
}
```

### Specifying a Custom Query

Our `characters` query allows us to get an array of characters by passing the `isMonster` query parameter. We'll need to supply the actual SQL query to StepZen so that it knows how to get the values. To do this, we pass a `query` parameter to the `@dbquery` directive rather than a `table` parameter as in the prior example. The `?` in the query will be replaced by the value of `isMonster` being passed.

Let's take a look at our `character.graphql` with the finished `charactersFromBackend` query. This query supplies the `characters` query with data from MySQL:

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
}
type CharacterBackend implements Character {}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
  charactersFromBackend(isMonster: Boolean!): [CharacterBackend]
    @supplies(query: "characters")
    @dbquery(
        type: "mysql",
        query: "SELECT * FROM characters WHERE isMonster = ?",
        configuration: "MySQL_config")
}
```
Now we can upload and deploy it:

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```
Then let's try querying it:

```graphql
{
  characters(isMonster:true) {
    name
  }
}
```

You should get the following response:

```json
{
  "data": {
    "characters": [
      {
        "name": "Black Knight"
      },
      {
        "name": "Ghost of Captain Cutler"
      },
      {
        "name": "Phantom"
      },
      {
        "name": "Miner Forty-Niner"
      }
    ]
  }
}
```
## Stitching Types Together

We have a schema with two types, character and episode, that pull real data from MySQL. However, they aren't tied together in any way. I cannot get the episode that a character was in right now without making two queries. This may be how it often works with REST-based APIs, but certainly not with GraphQL. Let's address that.

What we want is that when we get a character, it gives the associated episode that they appeared in. To do this, we're going to use another custom directive `@materializer`. Let's look at the finished `character.graphql`, then we'll cover the specifics of how it is configured. They key difference to notice below is the `episode` field within the `Character` interface.

```graphql
interface Character {
  id: ID!
  name: String!
  isMonster: Boolean!
  episodeID: ID!
  episode: Episode
    @materializer(
      query: "episode"
      arguments: [{ name: "id", field: "episodeID" }]
    )
}
type CharacterBackend implements Character {
  id: ID!
  name: String!
  isMonster: Boolean!
}
type Query {
  character(id: ID!): Character
  characters(isMonster: Boolean!): [Character]
  characterFromBackend(id: ID!): CharacterBackend
    @supplies(query: "character")
    @dbquery(type: "mysql", table: "characters", configuration: "MySQL_config")
  charactersFromBackend(isMonster: Boolean!): [CharacterBackend]
    @supplies(query: "characters")
    @dbquery(
      type: "mysql"
      table: "characters"
      query: "SELECT * FROM characters WHERE isMonster = ?"
      configuration: "MySQL_config"
    )
}
```
We've created an `episode` field on our character that returns an instance of the `Episode` type. It uses the `@materializer` to call the query `episode` on the Episode type that we defined within our `episode.graphql`. The `id` argument that the query is looking for will be populated with the `episodeID` from the character.

Let's upload and deploy it.

```bash
stepzen upload schema scoobyapi/schema --dir=. &&
stepzen deploy scoobyapi/scoobydoo --schema=scoobyapi/schema --configurationsets=scoobyapi/config
```
And try querying it, asking for a list of characters who are monsters and the name of the episode that they appeared in:
```graphql
{
  characters(isMonster:true) {
    name
    episode {
      name
    }
  }
}
```
Let's see the result:
```json
{
  "data": {
    "characters": [
      {
        "episode": {
          "name": "What a Night for a Knight"
        },
        "name": "Black Knight"
      },
      {
        "episode": {
          "name": "A Clue for Scooby Doo"
        },
        "name": "Ghost of Captain Cutler"
      },
      {
        "episode": {
          "name": "Hassle in the Castle"
        },
        "name": "Phantom"
      },
      {
        "episode": {
          "name": "Mine Your Own Business"
        },
        "name": "Miner Forty-Niner"
      }
    ]
  }
}
```

## Where To Go From Here

What we've touched on here really only gives you a taste of the real capabilities of StepZen. Imagine you're getting some of your backend data from MySQL and others from various RESTful APIs. StepZen would allow you to tie all those pieces together into a single API much the same way we tied our character and episode data together. This offers you a way not only to GraphQL-enable your existing backend, but to tie together disparate pieces into a single API accessible at a single endpoint. I hope you'll take some time to explore StepZen further via [the documentation](https://my.stepzen.com/docs) and share your thoughts and feedback with us.


A step-by-step guide to building a custom GraphQL API using StepZen that connects to a real MySQL backend.


Building Your First GraphQL API Using StepZen


Many APIs have moved towards supporting GraphQL in addition to REST or even supporting it exclusively. However, if you need to consume a GraphQL API, you wouldn't be blamed for thinking you need to use React and/or a bunch of additional libraries just to get it to work. That's because many tutorials and sample code seem to work off the assumption that, if you're working with GraphQL, you are working with these libraries.

However, a query to a GraphQL API is just a properly formatted HTTP request. A GraphQL response is just JSON. You don't need any fancy libraries to handle either of these. In this tutorial, I want to take a different approach and show you how easy it is to call a GraphQL API from both Node and client-side JavaScript without libraries.

## The Basics of a GraphQL Request

Unlike RESTful APIs, GraphQL has a single endpoint. A typical GraphQL HTTP request is sent as a POST request, though GraphQL can respond to GET requests.

There are three pieces of data that can be sent with your GraphQL request: `query`, `operationName` and `variables`.

* `query` is required and contains (you guessed it) the GraphQL query. Since GraphQL functions via a single endpoint, the data that the endpoint responds with is entirely dependent upon your query. The query needs to be properly formatted GraphQL. Curious how to construct your queries? Check out my tutorial on [how to write GraphQL queries](https://stepzen.com/blog/how-to-write-graphql-queries).
* `variables` is optional and is a JSON object containing the value of any variables being passed to your query. For instance, if your query requires a variable of `id` (which will appear in the query as `$id`) then you'd need to send variables as the following:
    ```javascript
    {
    "id":1
    }
    ```

* `operationName` is also optional. It is used to specify which operation to run in the case where you have a query containing multiple [named operations](https://graphql.org/learn/queries/#operation-name).

If you send a GraphQL as a GET request, you'll need to pass the above as query parameters. Given that GraphQL queries can get long, this really isn't optimal, so we'll stick to POST requests. In this tutorial, we'll be hitting a simple Scooby Doo API that I created on [StepZen](https://stepzen.com) to connect to a MySQL data source (StepZen is in private alpha right now, but you can [request access here](https://stepzen.com/request-invite)).

## Sending Queries in Node.js

We can send queries via Node.js without any special libraries, leveraging the standard Node `https` library to form a POST request. Let's look at a simple example using no special libraries (note that I do use `dotenv` to pull in the API key for accessing my StepZen backend). In this example, I am only passing a `query`, which needs to be stringified before sending. Other than that, this is a fairly standard HTTP POST.

```javascript
const https = require('https');
require('dotenv').config();

const data = JSON.stringify({
  query: `{
    characters(isMonster:true) {
      name
      episode {
        name
      }
    }
  }`,
});

const options = {
  hostname: 'biggs.stepzen.net',
  path: '/scoobydoo/scoobydoo/__graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'Apikey ' + process.env.STEPZEN_API_KEY,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
```

Again, the data returned is just JSON, so if we were to run this, the output in the console would be:

```javascript
{
  characters: [
    { episode: [Object], name: 'Black Knight' },
    { episode: [Object], name: 'Ghost of Captain Cutler' },
    { episode: [Object], name: 'Phantom' },
    { episode: [Object], name: 'Miner Forty-Niner' }
  ]
}
```

### Simplifying the Request

Let's make this a little simpler by using something like [node-fetch](https://github.com/node-fetch/node-fetch) to reduce the amount of boilerplate code necessary to make the HTTP request. The node-fetch library implements the JavaScript fetch API from the browser in Node. This allows us to drop around 11 lines of code (a reduction of 25%), while also being much easier to read.

```javascript
const fetch = require('node-fetch');
require('dotenv').config();

async function getData() {
  const data = JSON.stringify({
    query: `{
        characters(isMonster:true) {
          name
          episode {
            name
          }
        }
      }`,
  });

  const response = await fetch(
    'https://biggs.stepzen.net/scoobydoo/scoobydoo/__graphql',
    {
      method: 'post',
      body: data,
      headers: {
        'Content-Type': 'application/json',
        'Content-Length': data.length,
        Authorization: 'Apikey ' + process.env.STEPZEN_API_KEY,
        'User-Agent': 'Node',
      },
    }
  );

  const json = await response.json();
  console.log(json.data);
}

getData();
```

The result of running the above would be identical to our prior example.

### Passing Variables

In this example, our query has a variable that needs to be passed (`$id`). In order to pass the variable, we need add a `variables` value to the data contained in the request body. This should be a JSON formatted list wherein each variable required by the query has a corresponding value in the JSON.

```javascript
const fetch = require('node-fetch');
require('dotenv').config();

async function getData(id) {
  const data = JSON.stringify({
    query: `query ScoobyDooWhereAreYou($id: ID!)  {
        character(id:$id) {
          name
          isMonster
        }
      }`,
    variables: `{
        "id": "${id}"
      }`,
  });

  const response = await fetch(
    'https://biggs.stepzen.net/scoobydoo/scoobydoo/__graphql',
    {
      method: 'post',
      body: data,
      headers: {
        'Content-Type': 'application/json',
        'Content-Length': data.length,
        Authorization: 'Apikey ' + process.env.STEPZEN_API_KEY,
        'User-Agent': 'Node',
      },
    }
  );

  const json = await response.json();
  console.log(json.data);
}

getData(1);
```

In this case, I am passing the ID value of 1, which, not coincidentally, returns Scooby Doo:

```javascript
{ character: { isMonster: false, name: 'Scooby Doo' } }
```

Now we know where Scooby Doo is.

## Sending Queries in Client-side JavaScript

Calling GraphQL queries via client-side JavaScript is nearly identical to the fetch example above with a couple of small differences. First, I obviously do not need to import a library to support fetch. Second, and more importantly, I do not have access to environment variables. It's worth emphasizing that, if your API requires passing some sort of API key or credentials, you will not want to perform this client side as your credentials will be exposed. A better solution would be to call a serverless function that has access to these credentials and then calls the API for you, returning the result. If your serverless function is written in JavaScript, the Node code from the prior examples would work. However, in the case that the API is wide open, let's look at how this is done (note that my example does have an API key, but please do as I say and not as I do...at least, in demos).

The following example calls my Scooby API to get a list of monsters and the episodes that they were featured in (sorry Scooby fans, I only have a handful of monsters from season 1 populated just yet). It then takes the results and displays them in the browser. While not important to the GraphQL call, I use [js-beautify](https://github.com/beautify-web/js-beautify) to properly format the JSON result to display and then [Prism](https://prismjs.com/) to color it.

```javascript
<html>
  <head>
    <title>GraphQL Query Example</title>
    <link href="css/prism.css" rel="stylesheet" />
  </head>
  <body>
    <pre><code class="language-json" id="code"></code></pre>
    <script src="js/prism.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/js-beautify/1.13.0/beautify.js"></script>
    <script>
      (async function () {
        const data = JSON.stringify({
          query: `{
    characters(isMonster:true) {
      name
      episode {
        name
      }
    }
  }`,
        });

        const response = await fetch(
          'https://biggs.stepzen.net/scoobydoo/scoobydoo/__graphql',
          {
            method: 'post',
            body: data,
            headers: {
              'Content-Type': 'application/json',
              'Content-Length': data.length,
              Authorization:
                'Apikey DONOTSENDAPIKEYS',
            },
          }
        );

        const json = await response.json();
        document.getElementById('code').innerHTML = js_beautify(
          JSON.stringify(json.data)
        );
        Prism.highlightAll();
      })();
    </script>
  </body>
</html>
```

The result of running this code is the JSON response containing the characters and episode data displayed in the browser.

![browser output](/images/blog/web-output.png)

Obviously, you won't typically want to simply display the result of a query to a user, so let's look at how you would use the data returned.

## Consuming GraphQL Query Responses

One of the great things about GraphQL is that the response is just plain JSON, so consuming the data is easy. The nicer part of this is that the response mirrors the query, meaning that you don't need to spend a lot of time parsing through documentation about the response. So, let's quickly take the example above and utilize the returned data rather than simply displaying it.

The code below takes the JSON response and then transforms it into HTML (using template literals) to append the items to an HTML list.

```javascript
<ul id="monsterList"></ul>
<script>
  (async function () {
    const data = JSON.stringify({
      query: `{
    characters(isMonster:true) {
      name
      episode {
        name
      }
    }
  }`,
    });

    const response = await fetch(
      'https://biggs.stepzen.net/scoobydoo/scoobydoo/__graphql',
      {
        method: 'post',
        body: data,
        headers: {
          'Content-Type': 'application/json',
          'Content-Length': data.length,
          Authorization:
            'Apikey DONOTSENDAPIKEYS',
        },
      }
    );

    const characterData = await response.json();
    const templateFn = (name, episode) => `<li>${name} (${episode})</li>`;
    const monsterList = document.getElementById('monsterList');
    characterData.data.characters.map((character) => {
      monsterList.insertAdjacentHTML(
        'beforeend',
        templateFn(character.name, character.episode.name)
      );
    });
  })();
</script>
```

The output of running this simple example is an unordered list of characters with the episode they appeared in.

![HTML output](/images/blog/list-output.png)

## Where To Go From Here

The goal here is not to dissuade anyone from using a GraphQL client library for performing GraphQL queries. They offer far more capabilities than the simple ones I've discussed here. In addition, many have features designed to make it easy to integrate with a frontend framework (like React, Vue, Angular). However, it's important for anyone exploring GraphQL, especially when comparing it to REST, that it's clear that consuming GraphQL does not require any external dependencies. If you're interested in exploring some of the JavaScript libraries, here are a few of the popular ones:

* [Apollo Client](https://github.com/apollographql/apollo-client)
* [urql](https://formidable.com/open-source/urql/)
* [Relay](https://relay.dev/)
* [GraphQL Request](https://github.com/prisma-labs/graphql-request)


A GraphQL query is just a standard HTTP request, no special libraries needed. Let's look at how to create one in JavaScript and Node.js.


Consuming GraphQL in Plain JavaScript

Wouldn't it be great if it were as easy to create a GraphQL API from a Google Sheet as it is to share a Google Sheet with someone?


An Instant GraphQL API Using Google Sheets


GraphQL is often touted for its efficiency when consuming data from APIs. There are two key aspects to its efficiency:

1. **You get only the data you need**. GraphQL will only respond with the fields you specify, meaning it does not need to send unnecessary data across the wire, potentially saving your application - and your users - significant amounts of data over the course of numerous transactions.
2. **You get all the data you need in a single request.** Rather than spread different parts of the data across multiple endpoints, GraphQL lets you get all the data you require from a single request. For example, I can get user information and their order information in a single query rather than hitting two separate endpoints.

Both of these benefits are made possible by the way GraphQL lets you constuct a query, but learning how to write a GraphQL query can take some practice. In this article, we'll look at some of the basics of constucting a query in GraphQL to help you get started. In this post, we'll focus on retreiving data from a GraphQL API (as opposed to modifying, or mutating, the data).

## Getting Set Up

More and more companies are adopting GraphQL for their APIs. GitHub was a early adopter of the technology. The GraphQL spec was open sourced in 2015 and the [GitHub GraphQL API](https://docs.github.com/en/free-pro-team@latest/graphql) was announced [back in 2016](https://github.blog/2016-09-14-the-github-graphql-api/). Pretty much anything you can do in GitHub, you can do via their GraphQL API. Today we are going to use it to retreive user and repository information in order to explore how you write GraphQL queries.

There are two ways to explore the API:

* Use their [API Explorer](https://developer.github.com/v4/explorer). If you log in to your GitHub account, it will allow you to explore the API schema and construct and run queries via a [GraphiQL](https://github.com/graphql/graphiql) interface.
* The alternative is to use a desktop API explorer. If you're a REST API consumer, you may be comfortable using something like [Postman](https://www.postman.com/), which, you'll be pleased to know, [does support GraphQL](https://learning.postman.com/docs/sending-requests/supported-api-frameworks/graphql/). In this post, I'll be using the free, [GraphQL Playground](https://github.com/graphql/graphql-playground), which is an Electron desktop app that can be installed via Homebrew or by [downloading the latest release](https://github.com/graphql/graphql-playground/releases/tag/v1.8.10).

In order to use the API outside the API Explorer, you'll need to [generate a Personal Access Token](https://github.com/settings/tokens). If you choose to use GraphQL Playground, you'll first need to add the API endpoint of `https://api.github.com/graphql`. If you try to run anything, you'll get a 401 error though. To fix this, add an authorization header in the HTTP headers (located on the bottom left side of the application window):

```json
{
  "Authorization":"Bearer MY_TOKEN"
}
```

![HTTP Headers in Playground](/images/blog/playground_setup.png)

Once the HTTP headers are set up, you should be able to click on the Docs tab on the far right to explore the types and queries available within the GitHub API.

![Playground Schema docs](/images/blog/playground_schema.png)

Ok. We're finally ready to start building a query.

## Creating Your First Query

Let's start with a relatively simple query to find out how many people are following the topic of GraphQL on GitHub using the `topic` query. In a RESTful API situation, this might involve calling an endpoint such as `/v3/search/topics` which would return all the details we need. However, every GraphQL query calls the same endpoint, so you must define what you are querying in the request. Luckily, GraphQL IDEs like GraphiQL or the GraphQL Playground will offer code hinting.

Let's start by calling the `topic` query:

```graphql
{
  topic
}
```

You may notice that your GraphQL IDE indicates that there is an error in your request.

![GraphQL query error](/images/blog/query_error.png)

As the error indicates, the `topic` query expects a `name` argument of type string. So let's add our first argument, which is placed in parentheses after the query:

```graphql
{
  topic(name: "graphql")
}
```

You'll note that we're still seeing an error. Why? Well, the way that GraphQL is able to supply you _only the data you need_ is by requiring that you specify the fields you require within your query. There is no equivalent of `select *` in GraphQL, and this is [for a number of good reasons](https://productionreadygraphql.com/blog/2019-10-24-why-you-cant-select-all-fields-on-a-type-in-graphql). So, lets specify some fields within our query.

The `topic` query has 6 fields available, but really we're only interested in the number of people following it, or the `stargazersCount` field:

```graphql
{
  topic(name: "graphql") {
    stargazerCount
  }
}
```

Finally, no errors. Let's run our query. Here's the response:

```json
{
  "data": {
    "topic": {
      "stargazerCount": 12201
    }
  }
}
```

You'll notice that the response matches the query, meaning we don't need to waste time figuring out the structure of the response (something I have spent inordinate amounts of time doing in the past).

### Arguments

In the above example, we had a single argument that was a string. Arguments can be any of the [GraphQL basic types](https://graphql.org/graphql-js/basic-types/) but they can also be an enum or even a custom object type. For example, GitHub's `search` query takes a `searchType` argument that is an enum with the possible values of `ISSUE`,`REPOSITORY` or `USER`.

```graphql
{
  search(query: "GraphQL", type: REPOSITORY) {
    repositoryCount
  }
}
```

Meanwhile, for example, the `repositories` object within a `user` query takes a custom object argument of type `RespositoryOrder` that specifies both the field to order by and the direction in which to order. Here's a snippet from the larger query we'll look at later in this article:

```graphql
...
repositories(orderBy: {field:UPDATED_AT, direction: DESC}) {
...
```

The point here is that GraphQL allows APIs to support very complex querying capabilities in arguments.

## Nested Objects

So far, we have a very simple query that gets only a single field. Let's make this a little bit more complex by adding a nested object to get multiple sets of data in a single query. In this case, let's get a list of related topics to GraphQL within GitHub using the related topics object.

```graphql
{
  topic(name:"graphql") {
    stargazerCount
    relatedTopics {
      name
      stargazerCount
    }
  }
}
```

You'll see that we need to specify the object and then again the fields within that object that we want to retrieve. In this case, `relatedTopics` did not require an arguement. However, if you look at the docs, you'll see that it does have an optional argument of `first` that defaults to 3, meaning it will only send the first 3 results. Let's define that to give us 10 (the maximum the API allows):

```graphql
{
  topic(name:"graphql") {
    stargazerCount
    relatedTopics(first: 10) {
      name
      stargazerCount
    }
  }
}
```

As you can see, you can specify arguments not just on the primary query but on nested object queries as defined by the schema.

## Aliases

Now let's imagine that we want to get the stargazer count for both GraphQL and JavaScript in a single request. You might try something like this:

```graphql
{
  topic(name: "graphql") {
    stargazerCount
  }
  topic(name: "javascript") {
    stargazerCount
  }
}
```

That would give you an error however because we have defined conflicting queries in a single request. To solve this, we need to use an alias on each of the queries:

```graphql
{
  graphql:topic(name: "graphql") {
    stargazerCount
  }
  javascript:topic(name: "javascript") {
    stargazerCount
  }
}
```

This will return a response containing the aliases you specified.

```json
{
  "data": {
    "graphql": {
      "stargazerCount": 12203
    },
    "javascript": {
      "stargazerCount": 73700
    }
  }
}
```

It's worth noting that the alias can be any string you want, though it cannot start with a number or contain any special characters other than an underscore (though it can start with an underscore).

## Fragments

Let's imagine that we wanted to make this query get more than just the `stargazerCount`. We wouldn't want to have to repeat this code for each aliased query. This is where fragments come in. They can represent reusable pieces of query code. For example, instead of writing this:

```graphql
{
  graphql:topic(name:"graphql") {
    stargazerCount
    relatedTopics(first: 10) {
      name
      stargazerCount
    }
  }
  javascript:topic(name:"javascript") {
    stargazerCount
    relatedTopics(first: 10) {
      name
      stargazerCount
    }
  }
}
```
...we can write this:

```graphql
{
  graphql:topic(name:"graphql") {
    ...topicDetails
  }
  javascript:topic(name:"javascript") {
    ...topicDetails
  }
}

fragment topicDetails on Topic {
	stargazerCount
    relatedTopics(first: 10) {
      name
      stargazerCount
    }
}
```

We define the fragment and give it a name (`topicDetails` in this case). You must define the type it is a fragment on (`Topic` in this case) for validation purposes. Then we can reuse the fragment by referencing it's name prefixed by three dots (i.e. `...topicDetails` in this case) wherever we need to reuse it. While we didn't save a ton of code in this example, this can be particularly useful when you find yourself repeating large chunks of code in a complex query.

## Variables

The last topic I want to discuss here is variables. Let's imagine I wanted to create a query that gets the user profile information and recent repositories for a user. This wouldn't work if I had to pass a hardcoded user string. Instead, GraphQL allows me to define a variable and then pass in a variables object to the query to populate the variables.

First, let's look at our query. This query basically gives us everything we might want to know to construct a profile page for a GitHub user (perhaps for a developer portfolio home page or something):

```graphql
query GitHubUserProfile($username: String!)  {
  user(login:$username) {
    name
    company
    bio
    twitterUsername
    websiteUrl
    url
    repositories(first: 10, privacy: PUBLIC, orderBy: {field:UPDATED_AT, direction: DESC}) {
      totalCount
      edges {
        node {
          name
          description
          url
        }
      }
    }
  }
}
```

Not related to variables, but up until now we have been using an anonymous operation (i.e. wrapping the query in curly braces), but best practice says we should define the operation type and name. In this case, our operation type is a `query` and the name is `GitHubUserProfile`. There are other operation types such as a mutation, which modifies data on the server, and a subscription, which subscribes to updates to changes from the server.

You'll notice I have defined a variable `$username` (all variables must be prefixed by a `$`) of type string. The exclamation point (`!`) indicates that this variable is a required argument. Within the `user` query we now reference the `$username` variable as the value for the `login` argument.

To specify that argument, we need to pass in a JSON object containing a value for `username`. We can do that in GraphQL Playground via the variables tab in the bottom left of the application.

![GraphQL variables](/images/blog/variables.png)

In this case, I've supplied my own GitHub username:

```json
{
  "username": "remotesynth"
}
```

...and you can see the result of running the query on the right (I won't duplicate the result here as it is rather long).

## Where To Go Next

This isn't a complete guide to queries. There are things like directives, for instance, that I have not touched on here. If you are looking for more details, I recommend the following resources:

* [Queries and Mutations](https://graphql.org/learn/queries/) on [graphql.org](https://graphql.org/)
* [Understanding Queries in GraphQL ](https://www.digitalocean.com/community/tutorials/understanding-queries-in-graphql) by Peter Ekene
* [GraphQL Core Concepts](https://www.howtographql.com/basics/2-core-concepts/) on [howtographql.com/](https://www.howtographql.com/)

Want to know why StepZen chose to use GraphQL? Check out [Why GraphQL?](https://stepzen.com/blog/why-graphql) by StepZen's CEO, Anant Jhingran.

## This Is Awesome, But My Backend Doesn't Support GraphQL

I think GraphQL offers a ton of power for queries, but you may be connecting to first-or-third-party RESTful APIs that haven't yet made the move or to a database backend that doesn't even have an API yet. If so, [StepZen](https://stepzen.com/) can help. We're building a way for you to enable all the backends you connect to to be accessible via a unified GraphQL API. You can learn more and sign up to get access to our private beta at [stepzen.com](https://stepzen.com/).


GraphQL queries are what allow GraphQL to be efficient in how it gets data, by allowing you to express only what you need but also exactly everything you need. In this post, we'll see how.


How to Write GraphQL Queries


There are two reasons why our first release uses GraphQL as the "One API for all Your Data."

## GraphQL is better for a frontend developer

A couple of months into StepZen’s journey, we realized two things:

1. Frontend developers are beginning to adopt GraphQL as the way to get data from backends, which is the raison d’etre for StepZen. The [2019 State of JavaScript survey](https://2019.stateofjs.com/ '2019 State of JavaScript survey') for example reports that [almost 40% of respondents have "used GraphQL, and would use it again"](https://2019.stateofjs.com/data-layer/), up from 20% in the 2018 survey; 50% of respondents have "heard of it, and would like to learn it."

2. The cognitive overload in understanding the schema and query structures in GraphQL is low--and there is enough open source tooling that helps along the way. There are no [Open API](https://swagger.io/resources/open-api/) to read: open up your favorite tool (such as [GraphQL Playground](https://github.com/graphql/graphql-playground), or [GraphiQL](https://github.com/graphql/graphiql)), and you have live documentation! In traditional REST calls--what you call and what you get back are only vaguely related: you have to parse the returned JSON and extract the bits yoy are interested in; whereas in GraphQL, what you get back is what you asked for (the shape of the response is the shape of the query). This is an awesome reduction in the cognitive overload on the frontend developer.

## GraphQL is better for a backend developer

There are technical reasons too as to why GraphQL is simply better as a universal API. This makes the job of the backend developer easier.

### Why REST as "One API for all your Data" leaves a lot of holes and GraphQL fixes most of these.

A REST API that would be "One API for all Your Data" would look something like this:

```bash
/oneAPI?q="select x where y"
```

As an example, x could be `orders.productTitle` and y could be `customers.email=johndoe@example.com`. But that immediately begs the question: what values of x are allowed, and what values of y are allowed, and what combination of these values are allowed?
In relational databases, all queries are executable, some fast, some slowly. But in a world where the backends are what the backends are, this is no longer true. To show this, consider a query where

```bash
y:products.Id=2
x:customers.email
```

This is a perfectly valid request: let us say that a product with `id=2` is recalled, and we might want to send mail to all customers who have bought the product.

However, typical backends are able to give data on what products a particular customer has bought, not which customers bought a particular product. Consequently, the above query might be very inefficient to execute (look through all orders of all customers and return those customers who had that particular product), or might not be executable at all.

So now, the backend developer must ensure that the frontend developer does not ask bad queries, and also, there are enough IDE integrations so that invalid queries are disallowed. So more work, more autogenerated code, longer and longer names of functions as helpers: `getProductDetailsByCustomerId` etc. All the stuff of nightmares.

This is much easier to solve in GraphQL. If the schema said:

```graphql
type Customer {
    email: String
    …
    products: [Product]
}
```

and there is nothing in the schema like

```graphql
type Product {
    id: Int
    …
    customers: [Customer]
}
```

Then the first query is executable, and the second query, simply by being absent in the schema, is not!

### GraphQL makes stitching easier

If a backend developer wants to stitch multiple pieces of data together (say customer details with all his orders), and return them in one call, she has two choices:

* Default to returning the stitched data (which would be wasted work if the frontend developer did not want that data), or
* She adds artificial parameters like `return=customer,orders` which introduce cruft and cognitive overload.

Instead, in GraphQL, introspection will tell the frontend developer whether she can query stitched data together (so, no cruft of artifical parameters), and would also let the developer ask or not ask for stitched data.

That is why, in our current release, and all near-term releases, we only expose GraphQL as the interface--GraphQL is better for the frontend developer, and GraphQL is better for exposing backends. It is the right choice for "One API for all Your Data."


GraphQL is a relatively new technology but it offers enormous benefits over the traditional RESTful solutions for frontend and backend developers.
