Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Mocking graph functionality to unblock client development


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

First, agree on your schema

To mock parts of your 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 additions/removals/changes can help make your schema more useful and expressive.

We recommended that your backend and client teams align on your 's structure ahead of time, even if you don't use mocking. Doing so enables you to create an expressive schema that accelerates all teams.

Creating a new schema

If you're creating an entirely new graph and corresponding , 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 s, we recommend using this sample by GitHub user setchy to mock your new 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 , see below.

To get started with the sample, run the following:

git clone
cd apollo-server-4-mocked-federation
npm install
cp .env.template .env

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

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 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 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/), 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 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 , see below.

To get started, run:

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

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 or changes to an existing one, it's important to publish that schema to Apollo for the following reasons:

  • Apollo Studio provides a centralized view of your , along with a mocked view of the schema.
  • By publishing to , 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 as a source of the , allowing for more straightforward development.

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

Edit on GitHubEditForumsDiscord