How to Introspect a GraphQL Endpoint

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

StepZen enables 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. To introspect a graphQL endpoint, see the following sections:

The Example API

For the example below, we'll be connecting to the SpaceX Land API.

Use The StepZen CLI

If this is your first time using the StepZen CLI, ensure you Install the StepZen CLI.

  1. Create a folder for your project:
mkdir graphql-stepzen
  1. Navigate into your folder:
cd graphql-stepzen
  1. Import the graphql template:
stepzen import graphql
  1. The StepZen CLI will then ask you what you'd like to name your endpoint. For this example, we'll use the suggested endpoint folder (api) and name (vetoed-ferret).
? What would you like your endpoint to be called? api/vetoed-ferret

Note: The folder name is generated randomly. You can enter whatever folder/endpoint-name you prefer if you'd like to customize it.

  1. After you choose your endpoint name, the command will create your folder and insert a stepzen.config.json file. This JSON file will hold the name of your endpoint to enable you to can skip this step in the future.
Created /Users/username/project-folder/stepzen.config.json
Downloading from StepZen...... done
  1. The CLI then will ask you 4 questions in order to connect to your GraphQL endpoint.
? 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

Below are descriptions of these questions:

What is the GraphQL endpoint?

This is the endpoint we'll be connecting to. In this case, the SpaceX Land API's documentation 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 example, we won't need to enter 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. You don't need to add any prefix like apikey, just input the API key string itself.<br/><br/>Note: 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?.

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 that is unlikely to be used by another GraphQL endpoint. In this case, we're prepending spacex_ so the types will be generated similar to: spacex_Launch.

Explore 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

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: Ensure 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 enable 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 don't have to write it ourselves!

Here's an example of one of the types that was automatically generated.

type spacex_CoreMission {
  name: String
  flight: Int
}

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

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