Embedding the Explorer

You can embed the GraphOS Studio Explorer in a webpage that you can then provide to your graph's consumers. This enables those consumers to test out operations from your own website.

For example, here's an embedded Explorer for an Apollo example graph. Try it out!

Embedding on the Apollo Server landing page

In Apollo Server v3.8.0 and later, you can use a built-in plugin to embed the Explorer directly on your server's landing page.

You use the ApolloServerPluginLandingPageLocalDefault plugin to configure the landing page in your local development environment, and you use ApolloServerPluginLandingPageProductionDefault for production environments:

1import {
2  ApolloServerPluginLandingPageLocalDefault,
3  ApolloServerPluginLandingPageProductionDefault,
4} from "@apollo/server/plugin/landingPage/default";
5
6let plugins = [];
7if (process.env.NODE_ENV === "production") {
8  plugins = [ApolloServerPluginLandingPageProductionDefault({ embed: true, graphRef: "myGraph@prod" })];
9} else {
10  plugins = [ApolloServerPluginLandingPageLocalDefault({ embed: true })];
11}
12
13const server = new ApolloServer({
14  typeDefs,
15  resolvers,
16  plugins,
17});

For more information, see the landing page plugin API reference.

Embedding on an arbitrary webpage

1. Open GraphOS Studio and select the graph variant you want to use with the embedded Explorer.

2. Go to the variant's Explorer page.

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

4. Use the options on the left side of the dialog to customize the embedded Explorer's appearance and behavior to your liking.

5. Still in the dialog, use the tabs above the code snippet to select the snippet for your use case:

   • Use React for React apps where you can npm install the @apollo/explorer package. You will need to install the optional dependency use-deep-compare-effect to use the React package.

   • Use JavaScript for non-React JavaScript apps where you can npm install the @apollo/explorer package.

   • Use Built file on CDN to use Apollo's CDN-hosted embedded Explorer.

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

Setting a default operation

You can prepopulate your embedded Explorer with an operation from one of your existing Explorer tabs. If you do, the embedded Explorer includes all the following automatically on load:

• The operation you selected

• Any variable names and values defined in the operation's associated tab that are used by the operation

• All header names and values defined in the operation's associated tab

To prepopulate a default operation, open the share dropdown in the Explorer and select Share as embed:

Authorization

If you're embedding a public variant, anyone with access to the embedded Explorer can view your schema and make queries against your variant.

If you're embedding a private variant, the embedded Explorer first asks users to authenticate by signing in to GraphOS Studio. Authenticated users are then asked to authorize their Studio account to be used on the embedding webpage.

After authorizing, users can access the embedded Explorer, which includes schema navigation and visible operation collections.

Options

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

1{
2  graphRef: 'acephei@current',
3  endpointUrl: 'https://acephei-gateway.herokuapp.com',
4  persistExplorerState: false,
5  initialState: {
6    document: `query ExampleQuery {
7  me {
8    id
9  }
10}
11`,
12    variables: { 'Variable1': 'ExampleValue' },
13    headers: { 'Header1': 'ExampleValue' },
14    displayOptions: {
15      showHeadersAndEnvVars: true,
16      docsPanelState: 'open',
17      theme: 'light',
18    },
19  },
20  handleRequest: (endpointUrl, options) => {
21    return fetch(endpointUrl, {
22      ...options,
23      headers: {
24          ...options.headers,
25          authorization: `token ${token}`
26      },
27    })
28  },
29}

Top-level options

These are the top-level fields you can include in the options object you pass to new EmbeddedExplorer:

initialState options

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

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

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

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

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

displayOptions options

These are the fields you can include in the initialState.displayOptions option you pass to new EmbeddedExplorer: