GraphQL Explorer

The GraphQL Explorer is a powerful, browser-based IDE for testing and developing GraphQL queries, built on the industry-standard GraphiQL interface, customized and embedded directly into Brightspot CMS. It provides an interactive environment for exploring your GraphQL schemas, writing queries, and testing API responses without leaving your CMS.

Overview

The GraphQL Explorer serves as your primary development tool for working with GraphQL endpoints in Brightspot. Whether you're using the GraphQL Content API (GCA), building custom endpoints with the code generator, or working with the GraphQL framework, the Explorer provides a consistent interface for testing and documentation.

Key features

• Interactive query editor with syntax highlighting and auto-completion
• Real-time schema documentation with searchable types and fields
• Query history to revisit and reuse previous queries
• Variable editor for parameterized queries
• Response viewer with formatted JSON output
• Dark mode for comfortable development
• Share queries via URL for team collaboration
• Multiple endpoint support to test different GraphQL APIs

Accessing the Explorer

The GraphQL Explorer is available in the Brightspot CMS under Admin > GraphQL > Explorer.

Alternatively, you can access it directly via URL:

1
https://your-brightspot-domain.com/cms/graphql/explorer

Interface overview

The GraphQL Explorer interface is divided into several key areas:

1. Endpoint selector

Located at the top of the interface, this dropdown allows you to select which GraphQL endpoint you want to query. Available endpoints include:

• GraphQL Content API (GCA)
• Any custom endpoints you've configured
• REST-mapped endpoints

2. Query editor (left panel)

The main text editor where you write your GraphQL queries, mutations, and subscriptions. Features include:

• Syntax highlighting for GraphQL query language
• Auto-completion (Ctrl+Space or Cmd+Space) for types, fields, and arguments
• Inline error detection with red underlines for syntax errors
• Prettify button to format your query
• Copy button to copy query to clipboard

3. Variables editor (bottom-left panel)

A JSON editor for defining query variables. This allows you to write parameterized queries that can be reused with different inputs.

Example:

1
{
2
  "id": "00000000-0000-0000-0000-000000000001",
3
  "limit": 10
4
}

4. Response viewer (right panel)

Displays the JSON response from your GraphQL query. Features include:

• Formatted JSON with syntax highlighting
• Collapsible sections to navigate large responses
• Copy button to copy response to clipboard
• Error messages with detailed debugging information

5. Documentation explorer (right panel, docs tab)

Interactive documentation automatically generated from your GraphQL schema. Features include:

• Searchable types and fields
• Field descriptions and deprecation notices
• Type hierarchies for interfaces and unions
• Argument documentation with types and default values
• Click-through navigation to explore related types

6. History panel (top-right)

Access previously executed queries from your session. Clicking a history item loads it back into the editor.

Writing your first query

Here's a simple example using the GraphQL Content API to fetch articles:

1. Select the GraphQL Content API endpoint from the dropdown
2. Type or paste this query into the editor:

1
query GetArticles {
2
  Article {
3
    results {
4
      _id
5
      _type
6
      headline
7
      publishDate
8
    }
9
  }
10
}

3. Click the Play button (or press Ctrl+Enter / Cmd+Enter)
4. View the response in the right panel

Using variables

Variables make your queries reusable and prevent query string manipulation. Here's an example:

Query:

1
query GetArticleById($id: ID!) {
2
  Article(_id: $id) {
3
    results {
4
      _id
5
      headline
6
      body
7
      author {
8
        name
9
      }
10
    }
11
  }
12
}

Variables:

1
{
2
  "id": "00000000-0000-0000-0000-000000000001"
3
}

Exploring the schema

The documentation explorer is your guide to understanding what data is available:

1. Click the Docs button in the upper-right corner
2. Click on Query to see all available query fields
3. Click on any field name to see its return type and arguments
4. Click on type names to navigate deeper into the schema
5. Use the search box to find specific types or fields

Query history

The Explorer automatically saves your query history for the current session:

1. Click the History icon in the toolbar
2. Browse your previous queries
3. Click any query to load it back into the editor
4. History persists across page reloads within the same session

Keyboard shortcuts

• Ctrl+Enter / Cmd+Enter: Execute query
• Ctrl+Space / Cmd+Space: Trigger auto-completion
• Shift+Ctrl+P / Shift+Cmd+P: Prettify query
• Ctrl+F / Cmd+F: Search within query
• Ctrl+D / Cmd+D: Select next occurrence of current selection

Sharing queries

You can share queries with team members by copying the URL from your browser. The URL includes:

• The selected endpoint
• The query text
• Variables (if any)

Simply copy the URL and send it to colleagues—when they open it, the Explorer will load with your exact query.

Tips and best practices

Use fragments for reusable fields

1
fragment ArticleFields on Article {
2
  _id
3
  headline
4
  publishDate
5
}
6

7
query GetAllArticles {
8
  Article {
9
    results {
10
      ...ArticleFields
11
      author {
12
        name
13
      }
14
    }
15
  }
16
}

Test error handling

Try queries with invalid IDs or missing required arguments to see how your API handles errors:

1
query TestError {
2
  Article(_id: "invalid-id") {
3
    results {
4
      headline
5
    }
6
  }
7
}

Use aliases for multiple queries

1
query GetMultipleContentTypes {
2
  articles: Article(limit: 5) {
3
    results {
4
      headline
5
    }
6
  }
7
  authors: Author(limit: 5) {
8
    results {
9
      name
10
    }
11
  }
12
}

Enable the @debug directive

Add @debug to see performance profiling information:

1
query GetArticles @debug {
2
  Article(limit: 10) {
3
    results {
4
      headline
5
    }
6
  }
7
}

Troubleshooting

Query won't execute

• Check for syntax errors (red underlines in the editor)
• Ensure required arguments are provided
• Verify you've selected the correct endpoint

Auto-completion not working

• Press Ctrl+Space / Cmd+Space to manually trigger
• Ensure the schema has loaded (check the Docs panel)
• Try refreshing the page if the schema seems stale

Can't see my custom endpoint

• Verify the endpoint is properly configured in Brightspot
• Check that you have permission to access the endpoint
• Refresh the page to reload the endpoint list

Response is empty or unexpected

• Verify your query syntax matches the schema
• Check field permissions and access controls
• Look for error messages in the response
• Use the @debug directive to see execution details

Next steps

Now that you're familiar with the GraphQL Explorer, you can:

• Learn about the GraphQL Content API (GCA) to query your content
• Explore persisted queries for production use
• Set up security controls for your endpoints
• Use the @debug directive for performance profiling