How to Introspect a GraphQL Endpoint

How to use an existing GraphQL API to generate a new schema.

StepZen allows you to connect an existing GraphQL API to your StepZen GraphQL API in order to integrate it with data from other sources like REST, databases and more. The easiest way to connect an existing GraphQL endpoint to StepZen is to introspect it and automatically generate the API.

The Example API

For the example below, we'll be connecting to the SpaceX Land 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/username/project-folder/stepzen.config.json
Downloading from StepZen...... done

In this case we accept 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 so that you can skip this step in the future.

Next, the CLI will ask you 4 questions in order to connect to your GraphQL endpoint. We'll go through each in detail in a moment.

? What is the GraphQL endpoint?  https://api.spacex.land/graphql
? Do you want to add an Authorization header? No
? Do you want to add a prefix? Yes
? What prefix should we use? spacex_

Generating schemas...... done
Successfully imported 1 schemas from StepZen

What is the GraphQL endpoint?

This is the endpoint we'll be connecting to. In this case, the SpaceX Land API's doocumentation specifies this endpoint: https://api.spacex.land/graphql.

Do you want to add an Authorization header?

Answer yes if the API requires authorization. In this case, we won't need to insert our authorization, since the SpaceX Land API does not require it.

What is your Authorization header?

This is where we input the header string provided by the API, if the API requires it (we won't see this question in our current example, but it will pop up if you select 'Yes' in response to 'Do you want to add an Authorization header?'). You don't need to add any prefix like apikey, just input the API key string itself.

Do you want to add a prefix?

A prefix can be prepended to each of your GraphQL types. We highly recommend doing this, since common type names (e.g., 'Customer', 'TimeZone' ) can cause confusion when multiple imported schemas have the same types. We'll specify the prefix in the next step.

What prefix should we use?

Choose a prefix not likely to be used by another GraphQL endpoint. In this case, we're prepending spacex_ so that the types will be generated like spacex_Launch.

Exploring the Generated Schema

Let's explore the schema code generated by the import process. If you open the folder, you'll see the following files.

.
├── _graphql
│   └── api_spacex_land.graphql
├── index.graphql
└── stepzen.config.json

First, at the bottom of the working directory, we have the stepzen.config.json. This file is used to configure the CLI. You can find documentation for it here.

The index.graphql tells StepZen how to assemble your schema from the various .graphql schema files in the project folder. In this case, we only have one, graphql/api_spacex_land.graphql. The index.graphql file will look like:

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

If we had more than one schema file, it would appear in the files: [] brackets as part of a comma-separated list of strings.

Our API doesn't require authorization, but if it did, you'd see a config.yaml file containing the configuration information that StepZen requires to connect to your backends. If it were required, it would look like:

configurationset:
  - configuration:
      name: schema_name.graphql_config
      Authorization: { { API_KEY_HERE } }

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

Lastly, the graphql/api_spacex_land.graphql is a 1300+ line schema that maps out the types, mutations and queries in the SpaceX Land API. This schema file will allow us to call queries and mutations on the SpaceX Land API using StepZen and even tie them into any of the other backends that StepZen integrates with.

The best part is that we didn't have to write it ourselves!

Here's an example of one of the types that was automatically generated. Notice that the prefixes that we specified are added:

type spacex_CoreMission {
  name: String
  flight: Int
}

The type CoreMission has been prefixed as we specified with spacex_. This way if you import or write another schema with a CoreMission 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:

schema explorer

Enter the following query into the left box:

query MyQuery {
  spacex_capsules {
    id
    reuse_count
    landings
  }
}

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

{
  "data": {
    "spacex_capsules": [
      {
        "id": "C105",
        "landings": 1,
        "reuse_count": 0
      },
      {
        "id": "C101",
        "landings": 1,
        "reuse_count": 0
      },
      {
        "id": "C109",
        "landings": 0,
        "reuse_count": 0
      }, [...etc]

Now you can access the data from the SpaceX Land API on your own GraphQL endpoint! This allows us to integrate it with other data from other sources into a single consolidated API. For example, if we had weather data in a database, we could use the weather information for a specific date and connect it to the SpaceX Land API to get the weather for a specific launch.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.