Creating a new subgraph
For your supergraph
This article helps you get started building a new subgraph that you can then add to your GraphOS supergraph.
- If you're building a new GraphQL API from scratch, we recommend starting from a template!
- If you already have a GraphQL API to use as a subgraph, see Starting with an existing API.
Starting from a template
The fastest way to create a new subgraph is to start with one of the templates provided by the Rover CLI. The
rover template command generates the skeleton of a new subgraph for you, so you can immediately begin defining your schema and implementing your resolvers.
If your installed version of Rover doesn't include the
template command (or if you don't have Rover installed at all), install the latest version.
Templates are currently available for the following libraries and languages:
|Go||Go (gqlgen)||View repository|
|Java||Spring GraphQL||View repository|
|Kotlin||GraphQL Kotlin||View repository|
|Python||Strawberry with FastAPI||View repository|
|Python||Ariadne with FastAPI||View repository|
|Rust||async-graphql with Axum||View repository|
|TypeScript||Apollo Server (TS)||View repository|
You start by running
rover template use, providing it the ID of your chosen template. For example, the following command creates a new directory called
my-subgraph that contains the boilerplate code for a subgraph written in TypeScript using the Apollo Server library:
rover template use subgraph-typescript-apollo-server my-subgraph
After generating the boilerplate code, you can start filling in your business logic. The generated code includes example resolvers for
Mutation, along with some entity types to use as your starting point. All templates also come with example GitHub Actions workflows to help with publishing your schema in CI/CD.
When you're ready to add your new subgraph to your supergraph, see below.
Starting with an existing API
If you have an existing GraphQL API that you want to use as a subgraph, confirm whether it uses a subgraph-compatible library.
- If it does, consult the library's documentation to determine how to enable its support for Apollo Federation (federation is an architecture that underlies every supergraph).
- If it doesn't, open an issue to let us know and we'll work with the library's maintainers to add support.
Adding to your supergraph
When you're ready to add a new subgraph to your existing GraphOS supergraph, do the following:
- Enable federation support in your subgraph library.
- If you built from a template, federation support is already enabled. Otherwise, consult the documentation for your chosen library.
- Check your schema against your existing supergraph and handle any conflicts.
- Set up your CI/CD pipeline to perform checks and also publish your subgraph schema.
After you publish your subgraph's schema for the first time, GraphOS recognizes it as part of your supergraph, and you can start querying for data from all of your subgraphs!
⚠️ Make sure you secure your subgraph so that only GraphOS can query it.