Docs
Try Apollo Studio

Apollo Sandbox

Use Studio tools without an Apollo account


Apollo Sandbox is a special mode of Apollo 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 Apollo 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.

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://flyby-locations-sub.herokuapp.com/

Schema diffs

If you log in to Apollo Studio from Sandbox, you can diff your Sandbox schema against any subgraph or monolith graph you have access to in the Apollo 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 (such as 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 in to Apollo Studio from Sandbox, you can run schema checks between your Sandbox schema and any graph you have access to in the Apollo registry.

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 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.

Sandbox subgraph check prompt

When you click Run a check, Sandbox first performs a composition check using your local subgraph schema and the published 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 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

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.

    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
Introduction
Next
Platform API