Tutorial: Create a GraphQL API for a GraphQL backend
Use the CLI command stepzen import graphql
to create a GraphQL API for a
GraphQL backend datasource.
This topic shows how to use the stepzen import mysql
CLI command to introspect a GraphQL
backend. The source code for the examples in this tutorial is stored in the Examples repository.
.graphql
GraphQL
Schema Definition Language (SDL) file, using the GraphQL directive @dbquery
to
connect to the GraphQL backend. See Connect a GraphQL backend for an example.In this tutorial, example, you'll be connecting to the publicly available SpaceX Land API, hosted on GitHub.
Generate the GraphQL Schema
- Create a workspace directory for your project; for
example:
mkdir graphql-tutorial
- Navigate into your new workspace directory:
cd graphql-tutorial
- Import the
graphql
template:stepzen import graphql
The command starts creating a GraphQL API, and prompts you for information as shown in the following steps.
- Name your endpoint when prompted by the API Connect Essentials 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
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 contains the name of your endpoint.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
? What is the GraphQL endpoint URL?
This is the endpoint you'll be connecting to; for this tutorial use the following the SpaceX Land API endpoint:
https://api.spacex.land/graphql? Prefix to add to all generated type names (leave blank for none)
A prefix can be prefixed to each of your GraphQL types; this is highly recommended because common type names (for example,
Customer
, orTimeZone
) 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 the same domain.For this tutorial, specify the following prefix:
spacex_
so the types will be generated with names such as:spacex_Launch
.? Add an HTTP header (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 because the SpaceX Land API does not require it. Leave this response blank.
? Do you want to add an Authorization header?
Respond with Yes to use an Authorization header, or No to skip it. If you choose to use the header, provide the header string in response to the next question.
? What is your Authorization header?
If you chose to use an 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.
Let's explore the schema code generated by the preceding steps. Open the directory to see the following files:
.
├── _graphql
│ └── api_spacex_land.graphql
├── index.graphql
└── stepzen.config.json
- The
graphql/api_spacex_land.graphql
file contains 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 API Connect Essentials, and even tie them into any of the other backends that API Connect Essentials 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 }
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. - The
index.graphql
file tells API Connect Essentials how to assemble your schema from the various.graphql
schema files in the project directory (in this example, you only have one,graphql/api_spacex_land.graphql
).The
index.graphql
file looks like the following example: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. - At the bottom of the working directory is
stepzen.config.json
, which is used to configure the CLI. - The API in this tutorial doesn't require authorization, but if it did, you'd see an additional
file in the directory, called
config.yaml
.The
config.yaml
file contains the following configuration information, which API Connect Essentials uses to connect to your backends:configurationset: - configuration: name: schema_name.graphql_config Authorization: { { API_KEY_HERE } }
Note: Theconfig.yaml
contains authorization information, so make sure that it is included in your.gitignore
before pushing to any Git branches.
Deploy and run your endpoint
Run the CLI command stepzen start
to deploy the generated GraphQL schema to API Connect for GraphQL. A GraphQL API is
immediately available on the endpoint URL.
- Execute
stepzen start
to deploy the generated GraphQL schema for your database to API Connect Essentials.A GraphQL API is instantly available on the endpoint you configured in the preceding section (
...api/dozing-fly
). You can query your GraphQL API from any application, browser, or IDE by providing the API key linked to your account. - Now run the following query:
query MyQuery { spacex_capsules { id reuse_count landings } }
The result pulls data from the PostgreSQL database, and looks like the following example:
{ "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.