Connect A GraphQL API to Your StepZen Data Layer
Tags: graphql, todayilearned, discuss, showdev
Published: 2021-07-30 17:56:03



_Originally [published on StepZen](https://stepzen.com/blog/connect-a-graphql-api-to-your-stepzen-data-layer)_

StepZen allows you to introspect GraphQL APIs easily to create your own schemas with a few commands.

Building a GraphQL layer with StepZen allows you consolidate data from any number of sources and [reduce complexity](https://stepzen.com/blog/decoupling-frontend-backend) in your schema. For example, if your backends include a REST API, a MySQL database, and a GraphQL API, you can create one point of reference for them all in the data layer with a single GraphQL endpoint.

In this post, I'll demonstrate how to get a GraphQL API connected to StepZen. StepZen can also connect to databases and REST APIs as well. If you're curious about those, [check out our docs](https://stepzen.com/docs).

## Getting Started

### Sign Up for StepZen

Create a [StepZen account](https://stepzen.com/request-invite) first, in order to get your API and admin keys (click the "My Account" button on the top right once you log in to see where they are).

Next, [install the StepZen CLI](https://stepzen.com/docs/quick-start) to be able to deploy your endpoint from the command line.


### Our Example API

I'll be using the [Everbase API](https://www.everbase.co/) for the following example. I chose it because it houses lots of real-world data that is fun to work with, and the free tier is sufficient for exploring StepZen's GraphQL import.

If you want to code along, you'll need to [sign up for an Everbase account](https://www.everbase.co/account/create) so that you can access [account keys](https://www.everbase.co/account/keys) that you'll need to use the API.

### Using The StepZen CLI

If this is your first time using the StepZen CLI, the first thing you'll need to do from the command line is run

```bash
stepzen login
```

You'll be prompted for your credentials. Use the ones from your account page:

```bash
What is your account name?: {ACCOUNT}
What is your admin key?: {ADMINKEY}
```

Now, make yourself a folder for your project and cd into it like:

```bash
mkdir graphql-stepzen && cd graphql-stepzen
```

From where you are now, run:

```bash
stepzen import graphql
```

The StepZen CLI will then ask you what you'd like to name your endpoint:

```
? What would you like your endpoint to be called? api/vetoed-ferret
Created /Users/luciacerchie/project-folder/stepzen.config.json
Downloading from StepZen...... done
```
In this case I am accepting the suggested endpoint folder (`api`) and name (`vetoed-ferret`), the latter of which is generated randomly. You can enter whatever folder/endpoint-name you prefer if you'd like to customize it. You'll notice that the command will also insert a `stepzen.config.json` file, which will hold the name of your endpoint.

Now, it will ask you 4 questions to connect to your GraphQL endpoint.

```bash
? What is the GraphQL endpoint? https://api.everbase.co/graphql
? Do you want to add an Authorization header? Yes
? What is your Authorization header? HEADER_HERE
? Do you want to add a prefix? Yes
? What prefix should we use? everbase_

Generating schemas...... done
Successfully imported 1 schemas from StepZen
```
#### Let's take these questions one by one and see what they mean.

1. `What is the GraphQL endpoint? https://api.everbase.co/graphql`

This is the endpoint we'll be using – in this case, Everbase, which [tells us the endpoint to use](https://www.everbase.co/docs/quick-start). The endpoint they give us specifies an auth parameter:
`https://api.everbase.co/graphql?apikey=your_key`

But since StepZen's CLI will ask for that next we leave it off: `https://api.everbase.co/graphql`.

2. `Do you want to add an Authorization header? Yes`

In this case we answered 'Yes' since the API we're connecting requires one (it's on your account page).

3. `What is your Authorization header?`

This is where we input the header string provided by the API. You don't need to add any prefix like `apikey `, just input the API key string itself.

4. `Do you want to add a prefix? Yes`

A prefix will be prepended to each of your graphql types. I highly recommend doing this, since common type names (e.g., 'Customer', 'TimeZone' ) can cause confusion between imported schemas.

5. `What prefix should we use? everbase_`

Here, I choose a prefix not likely to be used by another graphql endpoint.

## Exploring Your Import

If you open your main folder upon import success, you'll notice some imported files.

```
.
├── _graphql
│   └── api_everbase_co.graphql
├── config.yaml
├── index.graphql
└── stepzen.config.json
```

First, at the bottom of the working directory, you'll have `stepzen.config.json`, which I've mentioned before. It will look something like:

```json
{
  "endpoint": "api/vetoed-ferret"
}
```

This gives StepZen the information it needs to configure your endpoint.

Next up, we have `index.graphql`, which will look like:

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

```
`index.graphql` puts together the schemas for StepZen. If you had more than one, it would appear in the `files: []` brackets as part of a comma-separated list of strings.

Your `config.yaml` will look like:

```yaml
configurationset:
  - configuration:
      name: api_everbase_co_graphql_config
      Authorization: {{EVERBASE_API_KEY_HERE}}
```

This provides StepZen with the details it needs to make the connection to the Everbase API.

> NOTE: Make sure `config.yaml` is in your `.gitignore` before pushing to any git branches.

Lastly, in `graphql/api_everbase_co.graphql`, you'll see a 600+ line schema that you didn't have to write yourself! Feel free to click around and explore the types, queries, and inputs. One thing you might notice is the prefixes:

```graphql
"""
A city is a large human settlement.
"""
type everbase_City {
  """
  The continent.
  """
  continent: everbase_Continent!
  """
  The country.
  """
  country: everbase_Country!
  """
  The Geonames.org ID.
  """
[...]
}
```
The type `City` has been prefixed as we specified with `everbase_`. This way if you import or write another schema with a `City` type, there will be no type collision.

## Using the StepZen Schema Explorer

From the command line, run `stepzen start`. The StepZen Schema Explorer will pop up in your browser at `localhost:5000/api/foldername`:

![graphiql screenshot](https://codimd.s3.shivering-isles.com/demo/uploads/upload_0e25d2fa694909c49383bf233b748530.png)

Enter the following query into the middle box:

```graphql
query MyQuery {
  everbase_cities {
    geonamesID
    id
    name
    population
  }
}
```

You'll get your JSON response after hitting the 'play' button in the Explorer:

```json
{
  "data": {
    "everbase_cities": [
      {
        "geonamesID": 5376095,
        "id": "Q60537",
        "name": "Napa",
        "population": 76915
      },
      {
        "geonamesID": 1862569,
        "id": "Q15716",
        "name": "Hioki",
        "population": 46671
      },
      {
        "geonamesID": 3887781,
        "id": "Q13077",
        "name": "Hualpén",
        "population": 91773
      }, [...etc]
```

Now you can access the data from the Everbase API on your own GraphQL endpoint!

## Where To Go From Here

If you're interested in learning how to consume this data on your frontend, you can use [our docs](https://stepzen.com/docs/connecting-frontends/connecting-via-nodejs).

The StepZen docs also hold information on connecting other backends to your endpoint, like [REST APIs](https://stepzen.com/docs/connecting-backends/how-to-connect-a-rest-service) and [databases like PostGresQL](https://stepzen.com/docs/connecting-backends/how-to-connect-a-postgresql-database).

If you've got more questions, [hit us up on Discord](https://discord.com/channels/768229795544170506/768229795544170509), we'd love to chat. ;)