
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


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.
