Getting Started with GraphQL Backends

Use `stepzen import graphql` to create a GraphQL API for other GraphQL backends in minutes

There are two ways to create your GraphQL API with StepZen when you have a GraphQL backend.

Use the command-line interface (CLI) command stepzen import graphql to specify an existing GraphQL endpoint - StepZen introspects the endpoint and auto-generates a GraphQL schema for you.
Write your schema code in a .graphql (SDL) file. Use the GraphQL directive @graphql to connect the GraphQL backend, and with just a few lines of code, you have a working schema.) See How to Connect a GraphQL Backend for how to write your GraphQL schema using @graphql.

This topic shows how to use stepzen import graphql.

Notes:

Source code for this page is in our Examples repository.
For the example below, you'll be connecting to the SpaceX Land API.

Create a GraphQL Schema

The StepZen CLI can create a GraphQL API that connects data from a GraphQL backend.

Note: Before you begin: Install and set up your StepZen account and the CLI.

Create a directory for your project:

mkdir graphql-stepzen

Navigate into your directory:

cd graphql-stepzen

Import the graphql template:

stepzen import graphql

Name your endpoint when prompted by the StepZen CLI. For this example, use the suggested endpoint directory (api) and name (vetoed-ferret):
```
? What would you like your endpoint to be called? api/vetoed-ferret
```
Note: The directory name is generated randomly. You can enter whatever folder/endpoint-name you prefer to customize it.

After you choose your endpoint name, the command creates your directory and inserts a stepzen.config.json file. This JSON file holds the name of your endpoint so you can skip this step in the future.
```
Created /Users/username/project-folder/stepzen.config.json
Downloading from StepZen...... done
```
The CLI then prompts you to provide some information needed to connect to your GraphQL endpoint:
```
? What is the GraphQL endpoint URL?  https://api.spacex.land/graphql
? Prefix to add to all generated type names (leave blank for none)
? Add an HTTP header, e.g. Header-Name: header value (leave blank for none)

Generating schemas...... done
Successfully imported schema schema_name from StepZen
```
Below are descriptions of these questions:

What is the GraphQL endpoint URL?

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

Add an HTTP header, e.g. Header-Name: header value (leave blank for none)

Add authorization, if the API requires authorization. In this example, you don't need to enter API authorization, since the SpaceX Land API does not require it.

What is your Authorization header?

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.

Note: You are prompted to provide your Authorization header when you select Yes in response to Do you want to add an Authorization header?.

Add an HTTP header, e.g. Header-Name: header value (leave blank for none)

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

What happens next?

Let's explore the schema code generated by the steps above.

Open the directory to see the following files:

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

At the bottom of the working directory is stepzen.config.json. This file is used to configure the CLI. You can find documentation for it here.

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

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

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

The API doesn't require authorization, but if it did, you'd see a config.yaml file containing the following configuration information that StepZen requires to connect to your backends:

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.

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 enables you 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 you don't have to write it yourself!

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 with spacex_ as you specified earlier. This way, if you create another schema with a CoreMission type, there will be no type collision.

Deploy and Run your Endpoint

From the command line, run stepzen start. The StepZen Schema Explorer will be available on localhost:5001:

schema explorer

Enter the following query into the left box:

query MyQuery {
  spacex_capsules {
    id
    reuse_count
    landings
  }
}

You'll get a JSON response after pressing 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 you to integrate it along with data from other sources into a single consolidated API.

For example, if you had weather data in a database, you 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.

Learn More

To extend your schema or start from scratch to write your schema code yourself, you can use the GraphQL declarative construct @graphql. See How to Connect a GraphQL Backend.