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? 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 you'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, 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?.
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. You'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, 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 withspacex_
as you specified earlier. This way, if you create another schema with aCoreMission
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
:
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.