Skip to main content

API Explorer

The API Explorer is a powerful tool for understanding your project's specific 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

Understand your GraphQL API#

Before you start sending queries, you can use the API Explorer to better understand your project's GraphQL API.

Docs panel#

When you opening the docs panel, you'll find a detailed, searchable inventory of every query, mutation, and shape in your GraphQL API. When you click on a query or mutation, you'll find detailed information about their input and output types. When you click on a shape, you'll find detailed information about its available fields and their types.

tip

To quickly view the docs for any query or shape in the Explorer's GraphQL editor, hold down your computer's command key (the Command key on macOS or the Windows key on Windows) and click on any name in the editor. The docs panel should appear, preloaded with information about it!

Explore panel#

The Explore panel is similar to the docs panel since it shows all the queries and shapes that are available in your GraphQL API. But it's different in a powerful way: when you click on any query, mutation, or shape, it will be inserted right into the GraphQL editor!

You can use the Explore panel to pick and choose which queries you'd like to run and how much data you'd like them to return, all in an accessible, visual tool. It's a great way to get a feel for your API and what kinds of requests are possible.

Sending test requests#

The API explorer is most helpful when you're using it to try out queries to include in your website or application.

Editor#

The GraphQL editor will make it easy to build your queries with typeahead support, validation and typechecking, and bracket-matching. You can also collapse and expand nested segments of queries to manage writing more complex queries.

Results#

When you've got a query composed, it's time to hit Run Query to send it to your API! 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 there's only 1 error, you'll still get back a list).

Variables panel#

One powerful feature of GraphQL 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

Make sure you define your variables as a valid JSON object! If they aren't, otherwise 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.

Improving performance#

Slow-loading queries can really hurt the user experience of your application or website. That's why TakeShape's 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. Click on it any time to toggle it open, then drag from its edge to make it however tall you'd like. To dismiss it, click the "Debugger" title again to toggle it off.

The debugger will be empty until you run a query. After running a query, you'll see a diagram of its performance in the debugger. Click on any level of the tree to focus on it and get more information.

Quickly run queries in the API Explorer#

When you're using TakeShape's web client, you can quickly run queries in the API Explorer whether you're editing content in the data tab or adding new queries in the Schema tab. Simply look for the API Explorer quick action, a purple play button inside a circle, and click on it to instantly load a pre-written query!