This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.
GraphQL Yoga and the API Connect Essentials (formerly StepZen) product, that's available under API Connect, provide a simple setup experience for creating and federating GraphQL APIs.
One of the unique capabilities of GraphQL is that you can combine multiple GraphQL APIs into a single, unified GraphQL API. This pattern, often called GraphQL Federation, relies on GraphQL's specification that's at the core of every GraphQL API.
In this tutorial, you learn how to federate a GraphQL endpoint with API Connect Essentials and GraphQL Yoga. It describes the similarities and differences between the GraphQL server technologies.
Notice: StepZen was acquired by IBM in 2023 and renamed to API Connect Essentials. Some artifacts still use the StepZen name.
Prerequisites
Users should have experience with building GraphQL APIs.
Estimated time
It should take approximately 10 minutes to complete the tutorial.
After you install and set up GraphQL Yoga, two dependencies, graphql-yoga and graphql are installed. If you prefer typescript, modify package.json to reference types and to rely on a tsconfig.json.
{"compilerOptions":{"target":"es2016",/* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */"module":"commonjs",/* Specify what module code is generated. */"skipLibCheck":true/* Skip type checking all .d.ts files. */}}
Show more
Now that the dependencies are set up, you can generate a simple query with graphql-yoga in the main.ts file.
By running the npm run start command, a simple query is created, which you can explore by using this endpoint: http://localhost:4000/graphql
Step 2. Deploy an API Connect Essentials GraphQL endpoint
To deploy a GraphQL endpoint with API Connect Essentials, the file structure is not similar to the Node.js application we deployed in the previous step. Instead, the entier API is described inside GraphQL schema files:
.
├── rick.graphql
└── index.graphql
Show more
In the GraphQL schema that we are using in this tutorial, a @graphql directive connects to a public GraphQL endpoint. This API has information about the television show "Rick and Morty", and has details about its episodes and characters.
You can use the stepzen import graphql command to import and query the entire schema from a GraphQL endpoint. To keep this tutorial shorter, we are going to be querying the only list of characters from this endpoint.
type Name {name: String
}type Characters {results:[Name]}typeQuery{characters: Characters
@graphql(endpoint:"https://rickandmortyapi.com/graphql")}
Show more
From the root folder where you created these .graphql files, run the stepzen deploy --endpoint api/blog command and a new endpoint is deployed for you. The flag --endpoint is used here to set a name for the endpoint.
Step 3. Federate the API Connect Essentials endpoint with GraphQL Yoga
Return to the GraphQL Yoga application and replace the basic hello query with our characters query from API Connect Essentials.
The same GraphQL schema, excluding the @graphql directive, is going to be used as the typeDefs for GraphQL Yoga.
typeDefs: /* GraphQL */`
type Name {
name: String
}
type Characters {
results: [Name]
}
type Query {
characters: Characters
}
`,
Show more
To request data from the API Connect Essentials GraphQL endpoint https://ACCOUNT.us-east-a.ibm.steprz.net/api/blog/__graphql, be sure to change ACCOUNT to your account name and paste the following frontend JavaScript code snippet:
const request = awaitfetch(constants.url, {})
Show more
Find the apikey to query your API Connect Essentials GraphQL endpoint with the stepzen whoami --apikey command, and then paste it into the constants object.
The query is being passed as context['params']['query']. This query is taking the exact query that is made to the GraphQL Yoga server and running it in the API Connect Essentials GraphQL API.
const query = context['params']['query']
Show more
Run the npm run start command to explore the GraphQL Yoga endpoint at http://localhost:4000/graphql.
Summary and next steps
In this tutorial, you learned how to federate a GraphQL endpoint with two different GraphQL server technologies to query Rick and Morty data.
First, we've set up a GraphQL Yoga endpoint and then federated a new API Connect GraphQL endpoint. But it can also be done in the other order by querying GraphQL Yoga into an API Connect Essentials @graphql directive. We went in this direction because API Connect Essentials automatically deploys a GraphQL endpoint to the cloud. Being an open source technology, GraphQL Yoga does not deploy the endpoint to the cloud by default.
We'd love to hear what you're building with GraphQL and API Connect Essentials. Join our Discord Community and let us know.
About cookies on this siteOur websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising.For more information, please review your cookie preferences options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.