


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

# How to Secure API Routes for Jamstack Sites
On the landing page of our website, https://stepzen.com, you see an example of a query that can be used to provide a weather forecast for a visitor to your website, using their IP address as basis for the location.

![Localized Weather Query](/images/blog/htsarfjs_localizedweather.png "Localized Weather Query")

StepZen makes building the API backend to support a query like this easy by allowing you to stitch together data coming from multiple external APIs. In this article, we'll look at how you can use a query like this to personalize a site built with the Jamstack.

## Putting it on the Web

If you're using server-side rendering for your website, you're all set. You can just call this API when you render requests and viola, you're done.

But what if we want to do this on a Jamstack website? The majority of a Jamstack site is pre-rendered at build time via an SSG, but personalized content like this would need to be retrieved and rendered on the client-side using API calls from the browser. 

Today, making API calls from the browser is pretty easy. The [JavaScript fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) makes asynchronous API calls in the browser straightforward, but there are some things we should be concerned about:

* If the API I'm calling requires authentication, that authentication would be visible to any user visiting the page that makes the API call. I don't want to share my API keys with the world, so I'll need to figure out how to hide those.
* Depending on the API, I may want to restrict what users can do with it. In our example, I don't want users to be able to retrieve the weather for any location, I only want them to see the current conditions for their IP address. I pay for access to the API, and I don't want people to reverse engineer my website in order to reuse the API on my dime. 

![Browser API Call](/images/blog/htsarfjs_jam1.png "Browser API Call")

Today, one of the best ways to accomplish both these goals is to use a serverless function, such as AWS Lambda, GCP Cloud Run or Netlify Functions, to make the backend API call. We're creating a simple "wrapper" API that our web app can call, which takes care of authentication to the backend API and limiting what can be done with the API. Curious users will be able to determine how to call our serverless function, but that's all they will be able to do.

![Browser Serverless Function Call](/images/blog/htsarfjs_jam2.png "Browser Serverless Function Call")

This is such a common pattern that some providers and frameworks have built automation to make this very easy. In the next section we'll look at a live example.

## Building the Site

Next.js is a React framework with support for static and server rendering, which makes building a Jamstack site with dynamic content easy. Additionally, Next.js has a feature called [API Routes](https://nextjs.org/docs/api-routes/introduction), which makes building an API straightforward. API Routes are treated differently than pages, are server-side only. We will use API Routes to define the code for our serverless function.

Netlify is a hosting platform that makes it simple to host static sites, but they also provide serverless functions via Netlify Functions. On top of that, they have a plugin for Next.js sites that automatically creates serverless functions for any of the Next.js /api pages.

We will build our weather example using Next.js, creating an API call to retrieve the weather for the visitor's IP address. We'll then host the site on Netlify, and have Netlify automatically turn our API into a serverless function. Then we'll inspect the client-side code, and see how we've hidden our API key and restricted the capability of the API.

Our code is here: https://github.com/carloseberhardt/weather-test

Let's look at the structure of that app quickly, and point out a few key items.
```
.
├── components
│   └── weather.js
├── pages
│   ├── api
│   │   └── weather.js
│   ├── _app.js
│   └── index.js
```

The first key part of our web app is a React component defined in `components/weather.js` that retrieves and displays the forecast:
```javascript
import fetch from 'unfetch'
import useSWR from 'swr'

const fetcher = url => fetch(url).then(r => r.json())

export default function Weather() {
    const { data, error } = useSWR('/api/weather', fetcher)
    if (error) return <div>failed to load</div>
    if (!data) return <div>loading...</div>
    return <div><p>In {data.location.city}, it feels like {data.location.weather.feelsLike} {data.location.weather.units} with {data.location.weather.description}.</p></div>
}
```

We're simply fetching the `/api/weather` endpoint. Since all backend calls are handled in that code, we don't need to hide any API keys, or worry about people misusing our backend API.

The second key part of the app is the API implementation in `pages/api/weather.js`. Since that code will be executed server-side, we can use API keys or other secrets, which we can set as environment variables. We can also implement logic that restricts how the backend service is called. In this case we supply weather based on the IP address of the request, rather than any location. This further limits the value of trying to re-use our API code, making it less attractive for abuse.

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

const { STEPZEN_URL, STEPZEN_KEY } = process.env
const REFERERS=["https://weather-test.c3b.dev/", "http://localhost:3000/"]
// default ip if we fail to resolve or are running locally.
let ip = "128.101.101.101"

const graphQLClient = new GraphQLClient(STEPZEN_URL, {
    headers: {
        authorization: `Apikey ${STEPZEN_KEY}`
    }
})

export default async (req, res) => {
    // log headers, just while debugging. 
    console.log("headers: ", req.headers)
    
    // check sec-fetch-site header for same-origin
    if (req.headers["sec-fetch-site"] && req.headers["sec-fetch-site"] != "same-origin") {
        console.log("Not same-origin: ", req.headers["sec-fetch-site"])
        res.statusCode = 403
        res.send("FORBIDDEN")
        return
    } else if (! req.headers["sec-fetch-site"]) {
        // requiring sec-fetch-site header would current break on several popular browsers.
        // See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Site
    }

    // check referer header for known referrers
    if (req.headers["referer"] && ! REFERERS.includes(req.headers["referer"])) {
        console.log("Bad referer: ", req.headers["referer"])
        res.statusCode = 403
        res.send("FORBIDDEN")
        return
    }

    // query -- to find ip we check for x-forwarded-for header, then override that if the x-bb-ip header exists
    if (req.headers["x-forwarded-for"]) {
        ip = req.headers["x-forwarded-for"].split(',')[0]
    }
    if (req.headers["x-nf-client-connection-ip"]) {
        ip = req.headers["x-nf-client-connection-ip"]
    }
    let query = gql`
    {
        location(ip: "${ip}") {
            city
            weather {
                temp
                units
                feelsLike
                description
            }
        }
    }
    `
    
    try {
        const data = await graphQLClient.rawRequest(query)
        console.log(JSON.stringify(data))
        res.statusCode = 200
        res.json(data.data)
    } catch (error) {
        console.error("error:", error)
        res.statusCode = 500
        res.send("Server Error")
    }
}
```

Additionally, we've added a few checks to try to ensure the caller is coming from a known domain. Let's look at those a bit and talk about the limitations. 

First, we check to see if the request has a `sec-fetch-site` header set to `same-origin`. The W3C has started some work on providing servers some context about how a request was made which would allow servers to decide to serve the request or not. `sec-fetch-site` is one of these. Not all browsers support this yet, so we don't block the request if it is not present. To learn more about this header, see here: [Fetch Metadata Request Headers](https://w3c.github.io/webappsec-fetch-metadata/).

Next we check to see if the `Referer` header matches what we've defined in the `REFERERS` const. This is a simple way to see if the request is coming from our site (or locally).

In both checks, we "fail open" (if the headers aren't present, we allow the request through). Since we're already limiting what can be done with the API, we are not that worried about someone calling it directly from curl, for example. We could change the checks to require the presence of these or other headers if we wanted to be more restrictive.

Of course, these header checks can be circumvented by a caller if they know to try setting headers appropriately. It's not a locked gate, just a latched gate.

Our code also retrieves the caller's IP using either the `X-Forwarded-For` header, or if it's present, the `x-nf-client-connection-ip` header, which as of writing, is a header Netlify provides for us. See [this community discussion topic](https://community.netlify.com/t/is-the-client-ip-header-going-to-be-supported-long-term/11203) for more information.

Finally, we execute the query against our StepZen endpoint. 

## Deploying to Netlify
Now that we have the code for our site and our API-wrapping serverless function, we can deploy the site to Netlify. I'm not going to explain that process in detail, since Netlify has great documentation already: [Next on Netlify](https://www.netlify.com/with/nextjs/). I will point out a few things we do. 

First, when setting up our site we add two environment variables that we use in our API function: `const { STEPZEN_URL, STEPZEN_KEY } = process.env`. These are set to the endpoint of our StepZen GraphQL API and our StepZen API key, respectively.

Secondly, we install a terrific plugin the Netlify team provides, the [Next.js Build Plugin](https://github.com/netlify/netlify-plugin-nextjs#readme). This plugin will automatically create Netlify functions for any pages in your app that require server-side rendering, including anything you put in the /pages/api directory. This means we don't need to do any work at all to get our app working. No deploying a function manually, etc. Simply hook up your github repo and away you go.

In this example I also mapped my site to a custom domain, but that's not necessary. Just remember to adjust the `REFERERS` constant appropriately if you try this with your own deployment.

Once deployed to Netlify I can call up the page at https://weather-test.c3b.dev/ and see the current conditions at a location based on my IP address. 

![Screenshot of deployed web app](/images/blog/htsarfjs_weather-test.png "Weather test web app")

If I open up the developer console in my browser, I can see the fetch calls being executed with a request to https://weather-test.c3b.dev/api/weather: 

![Dev tools showing request details](/images/blog/htsarfjs_devtools.png "Dev tools request inspection")

You can see that no authentication information or details about the capabilities of the underlying APIs are revealed to the user. And if I try to hit that API URL directly from my browser I'll get a `FORBIDDEN` response, since the referer header is incorrect.

## Recap
Tooling for building and deploying Jamstack apps is rapidly improving, but there are still some challenges with the "A" in Jamstack that need solving. Here we've looked at one way to approach hiding credentials and limiting capabilities to prevent your users from misusing your APIs.


Securing API routes for Jamstack sites is important. Here's one way to do it.


How to Secure API Routes for Jamstack Sites


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


At StepZen, we believe there's a lot of power in providing developers with a single, consolidated API that brings together all of their disparate backends. But we also want to make that power available to developers as quickly and easily as possible. That's why we've been focused on creating tools that can help make the process of getting started building your API in StepZen even easier. Today I wanted to share two new capabilities we just released - `create-stepzen-app` and `stepzen start`. The two features work together to simplify the process of building and deploying your GraphQL API on StepZen.

Let's see how this works!

## create-stepzen-app

`create-stepzen-app` is a new tool that generates starter code to help you get begin deploying, testing and customizing your first GraphQL API using StepZen. You can use `create-stepzen-app` via npx:

```bash
npx create-stepzen-app my-project
```



You'll be asked a series of questions (mostly just your account details, which are preset if you've already run `stepzen login` on the StepZen CLI). Finally, it will offer you the option to choose from pre-existing templates.
![running create-stepzen-app](/images/blog/run-create-stepzen-app.gif)

For example, choosing `hello-world` sets up a simple StepZen API to get the weather from OpenWeatherMap using longitude and latitude.

```graphql
interface WeatherReport {
    date: Date!
    latitude: Float!
    longitude: Float!
    temp: Float
    feelsLike: Float
    description: String
    units: String
}

type OpenWeatherMapReport implements WeatherReport {}

type Query {
    weatherReport (latitude: Float!, longitude: Float!): WeatherReport
    openWeatherMapReport (latitude: Float!, longitude: Float!): OpenWeatherMapReport
        @supplies (query: "weatherReport")
        @connector(type: "__openweathermap_weather_location_connector__", configuration: "owm_default")
}
```

If you change directory into `hello-world`, we can explore a new feature of the StepZen CLI.

## stepzen start

We are continuously improving the developer experience while building, deploying and testing an API on StepZen. To that end, `stepzen start` eliminates the need to run multiple commands to upload schemas and configurations and then deploy them. It also eliminates the need to have something like GraphQL Playground installed to test queries against your new API. Instead, everything is taken care of by `stepzen start` and you can test via the embedded GraphiQL editor.

Let's see how this works. If you've generated a project using `create-stepzen-app` it has the default project structure that `stepzen start` assumes (don't worry if you don't as you can override the defaults, just run `stepzen start --help` for a list of options). For instance, running `stepzen start api/hello-world`, where `api/hello-world` are my `folder/schma-name`, from within the `hello-world` project will automatically upload the API and configuration, deploy it and then open a GraphiQL browser editor to test it.

![running stepzen start](/images/blog/stepzen-start.gif)

The GraphiQL editor that opens in a browser tab is already connected to my new API deployed on StepZen. This means I can immediately run queries against it for testing.

![embedded GraphiQL](/images/blog/graphiql-embedded.png)

Even better - `stepzen start` now watches any changes I make to my files and then automatically uploads and deploys them, making the build/deploy/test workflow much faster and more convenient.
## Where to Go From Here

If you're already a part of the StepZen private alpha, all you need to do is update the CLI to get accesss to `stepzen start`. Just run `npm update -g stepzen` and you're good to go! Nothing additional is required to use `create-stepzen-app`.

If you're not already part of the private alpha, you can [request an invitation](https://www.stepzen.com/request-invite).

To learn more about how to use both `create-stepzen-app` and `stepzen start`, check [the docs](https://my.stepzen.com/docs/helloworld).


We've added two new capabilities that make it even easier to get started with StepZen — create-stepzen-app and stepzen start. Let's see how they work.


An Improved Getting Started Experience


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


Take a look at Google Maps or Google Search.

![Map with marked route](/media/blog/map-with-marked-route.jpg)

You specify what you want, and Google delivers the answer. How? You don't know, and typically don’t care. The hard work is done by Google, and not you, the consumer. Google does not program each and every query that might get asked. Instead, it figures out at the time the query is submitted, the best way of answering it. Of course, it might cache popular queries.

Or take a look at a database query.

```sql
select product.id, product.title from products, category
where category.label = “kitchenware” and
product.categoryid = category.id
```

You specify what you want, and the database produces the right answer. How? You don't know, and typically don’t care. The hard work is done by the database, and not you, someone who wants the data.

This is the declarative world. A world in which the developer, the user, the consumer declares what they want, and the system assembles the right bits to satisfy it. It cannot possibly imagine all pieces of information that might be requested, and in all ways it can be requested. The execution logic has to be assembled when the request is made (query execution plan, caching excluded).

There is a different world--the procedural world. The developer anticipates what forms of requests will be made, and carefully programs her way through all of them. All of server side code (that you fullstack developers write), and all the JavaScript code (that you front-end developers write) uses procedural logic--full of if-then-else logic, error handling etc.

Neither is good nor bad, they are just different. As a developer, procedural code gives you more control. As a user, declarative code gives you more flexibility.

The world of APIs (where StepZen's cofounders spent a decade together), is procedurally built. What that means is that all the ways in which a user-developer of the API might request the data are programmed. You get APIs that do precisely what the API developer wants them to do. If some other way is needed, then either the API has to change, or a new API has to be built.

Let’s take an example. An e-commerce experience that requires the delivery status of all the open orders might be coded by calling an API:
`/deliveryStatus?email=”jane.doe@example.com”&status=”open”`

Furthermore, the API developer would have written some logic like:

> Fetch orders from customer system for “jane.doe@example.com”
>
> For each order:
> Fetch shipments from order system
>
> For each shipment
> Fetch delivery status from the carrier
> If undelivered, add to the return answer

Now imagine errors. What if the delivery system does not respond?
Now imagine changes. What if the frontend wants only those orders that are shipped by FedEx?
Now imagine multiple order systems. Which one should we get the information from?
Now imagine a completely different experience: “fetch price of products based on location.” OMG, the whole set of problems repeats themselves.

And the challenge here is not just complexity of the code in these. It is the time taken to code it (which means that the user experiences cannot be changed as quickly as the market demands). It is the brittleness of code. It is the creeping of concerns. It is the replication of business logic in multiple places. And for the frontend developer, it is another set of OpenAPI specs, opening up Postman, reading docs, seeing what parameter goes where. It's pain for the backend developer, pain for the frontend developer.

What if APIs could be built using declarative techniques? Like SQL, if there were one API that abstracts all the backends away and the frontend developer just asks for what she wants? Where the hard work of connecting the dots, of errors, of caching, of optimization, of scatter/gather etc. were all done by API middleware? What if the logic for execution just depends on the introspection of the backends--what they take as input, and what they produce as output?

This is what we are doing at StepZen. Our vision is **_One API for All Your Data._**

> Get the data you want.
> Using APIs built through configuration.
> And run zero infrastructure.

StepZen as a company is quite young. But Steprz (the StepZen team) are veterans, having built databases, API management systems, and run services in the cloud.

Obviously, our first steps will be just that--first steps. We believe in the power of GraphQL. So initially (perhaps always?) our APIs will be GraphQL APIs. We know backends have complexity. So initially we will give you a set of popular SaaS backends. We know the power of developers. So we will give you a set of connectors and schemas that you can stitch together, modify and add, creating your own "One API for All Your Data." And we will give you all of that, as a service. So that you have to run zero infrastructure.

We are just getting started, and we hope you will join us in our journey.


StepZen's CEO shares what inspired us to create StepZen and the complex problems we are working to solve for developers.


Why StepZen?


Software is magical. However, software doesn’t run in the ether (maybe because there is no ether - well, other than a pleasant-smelling colorless volatile liquid, not at all useful for running software :). Software needs real hardware to run on.

Early on at StepZen, we had a decision to make. Shall we build container deployed software that a developer could deploy on her infrastructure (or serverless), or do we provide StepZen-as-a-Service?

We decided on a SaaS model. That is why we say:

>Get the Data You Want.
>Using APIs Built Through Configuration.
>And Manage Zero Infrastructure.

The reasons for this choice are simple.

Our goal is to take away the friction between what the frontend developers want and what the backend data sources expose. Deploying infrastructure is a major friction that we would reintroduce if we were to follow a pure software model.

One of the reasons for the growth of APIs has been APIs-as-a-business-model. Stripe is a payments API. Twilio is a communications API. These are available as a service, which means the frontend developer doesn’t have to worry about payment or communications going down. Why should she now have to run the APIs that connect all of these together?

Getting things like retries, caching, protocol mediations, continuous improvements, auto-scaling, IP whitelisting, and so on right is extremely difficult to do as pure software.

Finally, our ability to innovate is much much higher in a SaaS model.

That said, our software is built on Kubernetes, so we can well imagine that we’d be available for on-premesis container deployments in the future. However, for now, just configure, and get an endpoint that is always on. That’s StepZen for you.




Two of StepZen's founders explore the benefits that made them decide to build StepZen using a Software as a Service (SaaS) model rather than a container model.


Why Build StepZen as a Service?


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.


Why GraphQL?

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


Stay up-to-date with StepZen