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
With TakeShape's API Explorer, you have a simple, reliable way 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.
TakeShape generates documentation for your project schema every time you deploy it, and you can access those docs from the API Explorer.
The easiest way to access docs about a particular query is by holding the command key (or control key on Windows devices) and selecting the name of the query that you've entered into your editor.
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.
TakeShape provides search functionality for your project's docs, which you can use by selecting the Docs Panel button above your editor. This will toggle the Documentation Explorer, which you can then use to search your docs.
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
If your variables are not defind as a valid JSON object, the results will display an error.
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.
Slow-loading queries can 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. 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.
Still need help? Get in touch with us.