Originally published on StepZen

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

Getting Started

Sign Up for StepZen

Create a StepZen account 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 to be able to deploy your endpoint from the command line.

Our Example API

I'll be using the Everbase API 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 so that you can access 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

stepzen login

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

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:

mkdir graphql-stepzen && cd graphql-stepzen

From where you are now, run:

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.

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

1. 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).

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

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

1. 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:

{
  "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:

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:

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:

"""
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:

Enter the following query into the middle box:

query MyQuery {
  everbase_cities {
    geonamesID
    id
    name
    population
  }
}

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

{
  "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.

The StepZen docs also hold information on connecting other backends to your endpoint, like REST APIs and databases like PostGresQL.

If you've got more questions, hit us up on Discord, we'd love to chat. ;)