Apollo Sandbox

Apollo Sandbox is a special mode of GraphOS Studio that helps with local development. Sandbox loads a running GraphQL server's schema via introspection, instead of fetching published schemas from the Apollo registry.

Sandbox provides access to the following GraphOS Studio features:

• The Explorer
• Schema reference
• Schema checks and diffs against registered graphs (for logged-in users)

You can use Sandbox offline and without an Apollo account. You also embed Sandbox on your own website.

Overview video

Connecting to a GraphQL server

When you open Sandbox, it automatically attempts to connect to a GraphQL server running at http://localhost:4000. You can use the box at the top of the Explorer to change this URL to any local or remote GraphQL endpoint that's accessible by your browser:

You can also change the default endpoint by providing a URL parameter.

1
https://flyby-locations-sub.herokuapp.com/

Schema diffs

If you log in to GraphOS Studio from Sandbox, you can diff your Sandbox schema against any subgraph or monolith graph you have access to in the GraphOS schema registry.

From Sandbox, open the Schema Diff page from the left navigation panel. Then use the dropdown menus to select any accessible organization, graph, and variant to compare against.

In addition to viewing the diff on this page, you can click Run a Check in the upper-right to run schema checks against the currently selected variant.

Schema checks

If you log in to GraphOS Studio from Sandbox, you can run schema checks between your Sandbox schema and any graph you have access to in the Apollo registry.

From Sandbox, open the Checks page from the left navigation panel. A dialog appears where you can select the organization, graph, and variant to run a check against and click Run a check. When the check completes, Sandbox displays a result summary. To view the result's full details in Studio, click Go to details.

Subgraph checks

You can run subgraph checks on supergraphs. If you're using Sandbox with a subgraph, you can use the subgraph dropdown to select which subgraph you want to check your changes against.

When you click Run a check, Sandbox first performs a build check using your local subgraph schema and the published schemas of your other subgraphs. If composition succeeds, Sandbox then performs operations checks as usual and displays the results of all checks. If composition fails, Sandbox does not perform operations checks and displays the composition error.

Offline Sandbox

You can use Sandbox without an internet connection if you're querying a graph running on localhost. To do so, open Sandbox in your browser at least once while connected to the internet. You can then use that browser to open Sandbox while offline.

Reconnecting

Sandbox automatically reconnects whenever your internet connection is restored. When it does, it might display a notification that your GraphOS Studio application version is stale by at least 24 hours. You can click the notification to update all your browser's open Studio tabs to the latest version.

Operation collections in Sandbox

See this section.

URL parameters

You can provide URL parameters to Sandbox to customize its initial state on page load. This can help users get started with Sandbox more quickly when opening Sandbox from a link.

The following URL parameters are supported:

For example, the following URL sets all supported parameters:

https://studio.apollographql.com/sandbox/explorer?endpoint=http://localhost:4200&document=query hello($name: String!) { hello(name: $name)}&variables={"name": "Sandbox User"}&headers={"Cache-Control": "no-cache"}

The example URL above opens Sandbox with the following initial state:

Embedding Sandbox

You can embed Sandbox on your own website. This can be useful for interacting with a GraphQL endpoint in your development environment or an endpoint with CORS restrictions.

Setup

1. Open Sandbox.

2. Under the Explorer's Settings tab, find Embed Sandbox and click Copy code snippet. A dialog with options and code snippets appears.

3. In the dialog, use the tabs to select the code snippet for your use case:

   • Use React for React apps where you can npm install the @apollo/sandbox package.
   • Use JavaScript for non-React JavaScript apps where you can npm install the @apollo/sandbox package.
   • Use Built file on CDN to use Apollo's CDN-hosted embedded Sandbox.

4. Click Copy to copy the snippet, then paste it into your HTML code.

Options

The EmbeddedSandbox object takes an options object with the following structure (individual options are described below):

1
{
2
  initialEndpoint: 'http://localhost:4000',
3
  handleRequest: (endpointUrl, options) => {
4
    return fetch(endpointUrl, {
5
      ...options,
6
      headers: {
7
          ...options.headers,
8
          authorization: `token ${token}`
9
      },
10
    })
11
  },
12
  hideCookieToggle: true,
13
}

These are the optional options you can include in the object you pass to new EmbeddedSandbox:

initialState options

These are the fields you can include in the initialState option you pass to new EmbeddedSandbox:

1
initialState: {
2
  document: `
3
  query ExampleQuery {
4
    books {
5
      title
6
    }
7
  }
8
`;
9
}

1
initialState: {
2
  variables: {
3
    userID: "abc123"
4
  },
5
}

1
initialState: {
2
  headers: {
3
    authorization: "Bearer abc123";
4
  }
5
}

1
initialState: {
2
  collectionId: 'abc1234',
3
  operationId: 'xyz1234'
4
}

1
initialState: {
2
  pollForSchemaUpdates: false;
3
}

1
initialState: {
2
  sharedHeaders: {
3
    authorization: "Bearer abc123";
4
  }
5
}