GraphQL Summit is back for three days of insights, hands-on learning, and fun to celebrate the GraphQL community. Join us in San Diego Oct 3-5.
Docs
Try Apollo Studio

Apollo Sandbox

Use Studio's devtools without an Apollo account


Apollo Sandbox is a special mode of Apollo Studio that is meant to be used for local development. Sandbox loads with a schema from introspection as opposed to a schema from the Apollo registry and provides access to a subset of Studio's devtools:

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

Sandbox can be used offline and without an Apollo account. You can use Sandbox in our hosted environment on Apollo Studio or run it yourself.

Launch Sandbox

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:

Sandbox URL field

To try out Sandbox with an example GraphQL API, you can set the URL to https://swapi-graphql.netlify.app/.netlify/functions/index.

Publishing schemas from Sandbox

⚠️ Sandbox does not yet support publishing subgraph schemas to Studio for a federated graph.

If you're signed in to Sandbox with your Apollo account, you can publish your GraphQL server's schema to a new Studio graph.

To do so, first click Publish at the top of the Explorer. The following dialog appears:

Publishing schemas to Studio from Sandbox
  1. Use the dropdown menu to choose an organization for your new graph.
  2. Provide a title for your graph.
  3. If you've created any Sandbox operation collections, you can copy those over to your new graph by checking the box.
    • This option doesn't appear if you haven't created any Sandbox collections.
  4. Click Confirm.

When Sandbox finishes publishing your schema, it redirects you to your new graph in Studio.

Schema diffs

If you log into Apollo Studio, you can diff the schema in your Sandbox against any graph you have access to in the 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:

Schema diff in Sandbox

If you're using Sandbox with a subgraph, this diff shows the schema as originally defined, not the generated subgraph schema that includes federation-specific fields like Query._entities. You can view the generated subgraph schema from the SDL page in Sandbox.

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 into Apollo Studio, you can run a Schema Check between the schema in your Sandbox and a graph you have access to in the Apollo registry.

Schema checks require usage reporting data from your GraphQL server.

Organization members with the Consumer role cannot run schema checks.

From Sandbox, open the Checks page from the left navigation panel:

Sandbox select variant for checks

Select any accessible organization, graph, and variant to check against and click Run a check. When the check completes, Sandbox displays a result summary:

Sandbox checks result

To view the result's full details in Studio, click Go to details.

Subgraph checks

You can run subgraph checks on federated graphs. 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.

Sandbox subgraph check prompt

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

Sandbox subgraph check result

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 to Apollo Studio whenever your internet connection is restored. When it does, it might display a notification that your Apollo Studio application version is stale by at least 24 hours. You can click the notification to update all of your browser's open Apollo Studio tabs to the latest version.

This notification indicates only that the Apollo Studio UI is out of date. Your Studio data is always kept up to date.

Operation collections in Sandbox

See this section.

Embedding Sandbox

In addition to using Studio's hosted version of Sandbox, you can also embed Sandbox on your own website. This may be useful for bootstrapping a GraphQL IDE onto a development endpoint 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.

    The following dialog appears:

    Sandbox embed dialog
  3. Within 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):

{
initialEndpoint: 'http://localhost:4000',
handleRequest: (endpointUrl, options) => {
return fetch(endpointUrl, {
...options,
headers: {
...options.headers,
authorization: `token ${token}`
},
})
},
includeCookies: false,
}

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

Name /
Type
Description
initialEndpoint

string

The URL of the GraphQL endpoint that Sandbox introspects on initial load. Sandbox populates its pages using the schema obtained from this endpoint.

The default value is http://localhost:4000.

You should only pass non-production endpoints to Sandbox. Sandbox is powered by schema introspection, and we recommend disabling introspection in production. To provide a "Sandbox-like" experience for production endpoints, we recommend using either a public variant or the embedded Explorer.

handleRequest

(url, options) => Promise

By default, the embedded Sandbox uses the fetch API to send requests from your webpage to your specified GraphQL endpoint. If you provide a custom handleRequest function, Sandbox uses it instead of fetch for all operations.

You might want to do this if you need to include specific headers in every request made from your embedded Sandbox.

includeCookies

boolean

By default, the embedded Sandbox uses the default fetch function to make requests, which passes { credentials: 'omit' }.

You can set includeCookies to true if you instead want the Explorer to pass { credentials: 'include' } for its requests.

If you pass the handleRequest option, this option is ignored.

Read more about the fetch API and credentials here.

Edit on GitHub
Previous
Get started
Next
Data privacy and compliance