Mocking graph functionality to unblock client development

As your organization builds out its supergraph, you might discover that your client teams are often waiting on subgraph owners to make agreed-upon changes to their schemas. During this time, you can mock parts of your supergraph as you develop both your clients and subgraphs, enabling teams to work in parallel without blocking each other.

First, agree on your schema

To mock parts of your supergraph effectively, both client and backend teams need to agree on the structure of those parts as part of a larger governance strategy and approval process. Alignment between these teams on schema additions/removals/changes can help make your schema more useful and expressive.

Creating a new schema

If you're creating an entirely new graph and corresponding schema, it's important first to familiarize yourself with schema best practices, such as those described in Apollo Odyssey, Principled GraphQL, and the Enterprise Guide.

For new schemas, we recommend using this sample by GitHub user setchy to mock your new schema in its entirety. This provides your client teams with a local (or hosted) instance of the schema to query against and begin mocking UI components with the mocked data.

To use this sample, you need to publish your schema to Apollo GraphOS. For details on the benefits of publishing to GraphOS, see below.

To get started with the sample, run the following:

1
git clone https://github.com/setchy/apollo-server-4-mocked-federation
2
cd apollo-server-4-mocked-federation
3
npm install
4
cp .env.template .env

Then, edit the .env file with the appropriate values from Apollo Studio and run the following to start the server:

1
npm run dev

The sample uses the @graphql-tools/mock package to power the mocks. You can customize the sample's behavior by following the instructions in the package's documentation page.

This gateway can then be used either locally (such as for local client development) or as a hosted gateway internally to be used by client developers.

The data is mocked, however it doesn't require any work from server teams to support and will match the schema as it exists within Apollo Studio. As we're using Apollo Studio for the schema, schema changes will automatically be pulled ensuring client developers are working on the latest version.

Modifying an existing schema

The process for making changes to an existing schema is similar to that for creating a new one, especially in terms of planning. As you add new features, it's important reach a design consensus early, especially for features that require extensive backend work (e.g., machine learning).

To mock proposed changes (such as adding a new type/field), we recommend using this sample created by Apollo's Solutions Architecture team. This sample requires a preexisting GraphQL API to be running. It works by allowing for a "patched" or modified version of your subgraph to run locally with mocked data, while using the remote API for all other data.

You'll need to publish your schema to GraphOS to use this sample. For details on the benefits of publishing to GraphOS, see below.

To get started, run:

1
mkdir mocked_gateway
2
export APOLLO_KEY=key_from_studio #replace with the actual key from Apollo Studio
3
cd mocked_gateway
4
touch proposed.graphql
5
npx github:@apollosolutions/apollo-faker-demo --graphref <yourgraph>@<variant> --remote https://yourapi.com/graphql

Then, modify the proposed.graphql file with the proposed changes. There are configuration options available via the @graphql-tools/mock package, and you can set these options as documented in the sample's README file, under step 5.

Why use GraphOS for a mocked server?

Now that you have either a new schema or changes to an existing one, it's important to publish that schema to Apollo GraphOS for the following reasons:

• Apollo Studio provides a centralized view of your schema, along with a mocked view of the schema.
• By publishing to GraphOS, the samples referenced above can automatically update on changes, allowing for a deployed version of the samples to be referenced by all developers.
• For client teams using code generation tools (especially those in Apollo's client libraries) it's possible to use GraphOS as a source of the schema, allowing for more straightforward development.

We recommend using a variant of your new/existing production graph ID. If considering mocking for schema changes, this also ensures proposed changes aren't breaking using schema checks against production traffic.