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

Create a project directory, initialize a `package.json`, and add the necessary dependencies.

```bash
mkdir stepzen-react-tutorial
cd stepzen-react-tutorial
npm init -y
npm i @apollo/react-hooks apollo-boost graphql react react-dom react-scripts
```

Create a `.env.local` file for our local environment variables and a `.gitignore` file.

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

You will need to include your StepZen API key into `.env.local`. We will enter the endpoint later in the tutorial.

```env
REACT_APP_STEPZEN_API_KEY=YOUR_KEY_HERE
REACT_APP_STEPZEN_ENDPOINT=YOUR_ENDPOINT_HERE
```

Include `.env.local` in your `.gitignore` file along with `node_modules` so these are not included if we decide to push this onto a public git repository.

```gitignore
node_modules
.env.local
```

Add the following scripts to your `package.json`.

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

Also include the following `browserlist`.

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

## 2. Setup React App

To setup our React frontend create the following:

1. Directories for `src` and `public`
2. An `index.js` file for our root component
3. An `index.html` file to load the root component

```bash
mkdir src public && touch src/index.js public/index.html
```

Our root component renders a title to the home page.

```javascript
// src/index.js

import React from "react";
import ReactDOM from "react-dom";

ReactDOM.render(
  <React.StrictMode>
    <h1>StepZen React Tutorial</h1>
  </React.StrictMode>,
  document.getElementById("root")
);
```

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 `Users` component

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

```bash
touch src/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/Users.js

import React from "react"

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

To see the `Users` component import the component into `index.js`.

```javascript
// src/index.js

import React from "react";
import ReactDOM from "react-dom";
import Users from "./Users";

ReactDOM.render(
  <React.StrictMode>
    <h1>StepZen React Tutorial</h1>
    <Users />
  </React.StrictMode>,
  document.getElementById("root")
);
```

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 the following:

1. A `stepzen` directory containing a `schema` directory
2. A `users.graphql` file for our `User` interface and `Query` type
3. An `index.graphql` file for our `schema`

```
mkdir stepzen stepzen/schema && touch stepzen/schema/users.graphql stepzen/schema/index.graphql
```

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

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

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

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.

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

type Query {
  getUsers: [User]
}

type UserBackend implements User {}

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

Our `schema` in `index.graphql` ties together all of our other schemas. For this example we just have the `users.graphql` file included in our `@sdl` directive.

```graphql
# stepzen/schema/index.graphql

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

### Deploy API

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

```bash
stepzen start stepzen-react-tutorial/users
```

A browser window with a GraphiQL query editor can be used to query your new endpoint.

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

This also deployed our API to `https://username.stepzen.net/stepzen-react-tutorial/users/__graphql`. Fill in your username and set the URL to the `REACT_APP_STEPZEN_ENDPOINT` environment variable.

## 4. Setup Apollo Client

There 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.

To setup the Apollo client wrap the `Users` component with `ApolloProvider` and pass in `ApolloClient` for our environment variables.

```javascript
// src/index.js

import React from "react"
import ReactDOM from "react"
import ApolloClient from "apollo-boost";
import { ApolloProvider } from "@apollo/react-hooks";
import Users from "./Users.js"

const {
  REACT_APP_STEPZEN_API_KEY,
  REACT_APP_STEPZEN_ENDPOINT
} = process.env;

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

ReactDOM.render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <h1>StepZen React Tutorial</h1>
      <Users />
    </ApolloProvider>
  </React.StrictMode>,
  document.getElementById("root")
);
```

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

```javascript
// src/Users.js

import React from "react"
import { useQuery } from "@apollo/react-hooks"
import { gql } from "apollo-boost"

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

Pass `GET_USERS_QUERY` into the `useQuery` hook. Check the `loading` indicator and display a loading message if loading is `true`. Otherwise display the `users`.

```javascript
// src/Users.js

export default function Users() {
  const { data, loading, error } = useQuery(GET_USERS_QUERY)
  const users = data?.getUsers
  
  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {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 the `users` array to display a list of each `user`.

```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 our GraphQL API. 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.

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/docs) 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/docs) 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/docs) 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/setup/setup-stepzen#setup-your-own-mysql-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/docs), 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.
