Skip to main content

API Explorer

The API Explorer is useful for experimenting with your project's GraphQL API. Here, we'll review the ways the API Explorer can help you build your project.

From the API Explorer you can:

  • Design and build GraphQL queries
  • Read generated documentation specific to your custom API
  • Send test requests and observe responses
  • Observe the path of a request through the API mesh
  • Measure query performance

The API Explorer allows you to test any changes to your project's schema or data right in the browser. Let's walk through the process of using the API Explorer.

Running queries and mutations​

You can type a query or mutation directly into the API Explorer's editor panel. The editor has code completion that will suggest queries as you type, validation and typechecking, and bracket-matching. You can also collapse and expand nested segments of queries to manage writing more complex queries. When you hover over a query, you'll see tooltips with helpful information, including links to your auto-generated documentation.

You can also have your query inserted into the API Explorer for you. Open the schema tab to the left, and select the play button to the right of any shape in your schema. The list query for that shape will be generated in your API explorer

To run your query, select the play button at the top of your API Explorer. Your results will appear in the panel to the right. If your query is valid, you'll see the data returned as a JSON object in the results pane. If your query is invalid, you'll get a list of errors instead. Even when only one error is returned, you will still receive a list.

Docs panel​

Documentation for your project schema is generated every time you deploy it, and you can access those docs from the API Explorer.

To access docs about a particular query, hold the command key (or control key on Windows devices) and select the name of the query.

You can also hover your cursor over any query, field or item in your selection set to get a tooltip popup. You can then select any part of the tooltip to see the related docs.

Documentation Explorer​

You can search your project's generated documentation from the Docs Panel itself.

Variables panel​

One useful GraphQL feature is the ability to provide variables to your queries. This makes it easy to write reusable queries for common queries like a paginated list.

After you define the variables you're using in your query, you can provide values for them by expanding the "Variables" panel underneath the GraphQL editor. The API Explorer will helpfully typeahead the names of variables you've already defined and notify you if a required variable is missing.

Variables are defined using JSON

If your variables are not defined as a valid JSON object, the results will display an error.

History panel​

After sending queries, you can revisit them at any time in your session by opening the History panel. When you select a query you've previously sent, it will load the query in the editor panel and the variable values you used in the variables panel.

You can also provide labels for queries in this panel, to distinguish them from others.

Improving performance​

Slow-loading queries can hurt the user experience of your application or website. That's why the API Explorer also comes with a handy debugger for analyzing your queries and finding opportunities to better optimize slow queries.

The debugger panel lives at the bottom of the explorer. Select its header to toggle it open. It can be resized vertically. You can toggle it off by selecting its header again.

The debugger will be empty until you run a query. After running a query, the debugger will show a diagram of its performance metrics. Select any item in the timeline to see more information.

Debugging authentication claims​

Sometimes when testing your API you'll want to debug queries or mutations that uses claims from an authentication provider like Auth0. With sufficient project permissions, a claims tab is displayed in the debugger panel. You can enable or disable mock claims using the switch. If enabled, the JSON you provide will be used as the authentication claims during execution.

Still need help? Get in touch with us.