GraphiQL Explorer 2.0: A power-user release!

[dwwoelfel]

At OneGraph, when we first released our GraphiQL Explorer to visually build GraphQL queries, we didn’t expect it spread across the GraphQL landscape so quickly: it’s been incorporated into Hasura, PostGraphile, the Apollo Client devtools, and recently it’s even landed in the default distribution for Gatsby! It’s been gratifying to see our investment in open tooling spread to such wide usage and bring delight to so many GraphQL users, beginner and expert alike.

Our initial release was just the beginning though, and today we’re pushing a new version with a visual overhaul and a whole slew of features for the more advanced users. Let’s take a quick tour of some of the new features:

Visual Polish

First out of the gate is a visual update. We’ve changed the selection fields for objects into arrows (like a file-system directory), and scalar fields into fixed-sized checkboxes. This should reduce much of the vertical/horizontal jumping with expanding fields, leading to a more “solid” experience.

Try this query in the new OneGraphiQL!

Multi-operation support

GraphiQL Explorer users can add multiple queries/mutations/subscriptions and edit them independently. Build up full documents incredibly quickly! Here’s me building a GraphQL document that’s a pretty decent Spotify player in ~30 seconds.

Try this terrific multi-operation query in the new OneGraphiQL

Query/Mutation/Subscription naming

Naming operations in GraphQL can be incredibly powerful, but it’s not an easily discoverable feature for newcomers. To address that, the explorer now teaches newcomers

1. That it’s possible to name operations and
2. The correct syntax on how to name operations

Also, it’s handy for advanced users as well!

Default names for new operations

A minor but important bit of polish that comes along with renaming support is default names - we always generate a name of the form My<OperationKind><Count>. No untitled.txt here!

Select-all-subfields

This is an advanced feature and can be potentially misused, but it’s been requested over and over again. So by popular demand, we’re adding this in a not-easily-discovered way: By holding option/alt while clicking on an object field, every subfield will automatically be selected. Be careful with this, you can easily end up over-fetching more data than you need!

Execute operation from the Explorer

An ergonomic improvement for keyboard accessibility - run the query from any input in the explorer without moving the mouse to click the “play” button. This uses the same key-binding (command-enter) that GraphiQL uses by default, so no learning necessary here.

Try the npm query in the new OneGraphiQL

Jump-to-operation-definition in Explorer

Along with the multi-operation support comes potentially long documents. Sometimes while scrolling through the query in the document editor, you want to see what fields are available - so we’ve changed the DOM structure of the explorer to make a focus-definition command much easier to implement (see the onegraphiql-example repo for instructions how)

Fragment support

And finally, fragment support. This is another advanced use-case as fragments aren’t used too much by newcomers, but for experienced developers, being able to explore a fragment this way is a blast.

Try this Stripe Refunds query in the new OneGraphiQL

The best way to explore APIs and create applications

The new explorer pairs so well with our GraphiQL Code Exporter that we’re able to build complex applications in under five minutes - see what the combination looks like in practice!

https://youtu.be/9bwrmkS7T-s?t=56

Future work

We’ve added a whole lot of features and polish with today’s release, but we still have plenty of ideas left. If you’re interested in contributing to GraphQL tooling that helps the whole community, jump into our repo and we’ll work alongside you!

1. Theming support

We made a bit of progress extracting the styling out from hard-coded style objects, but full theming support still isn’t implemented yet. Check out the great beginner task if you’d like to tackle this - as I mentioned before, we’re happy to help guide you, and it’d help projects like Altair and Hasura embed the explorer much more easily.

2. Automatic variable injection

When filling in an argument in the explorer with a value that started with $ (e.g. $login ), the explorer would reflect on the type of the input field (e.g. String!) and automatically insert it as a variable in the operation. This would significantly speed up making “production” queries, and would partially reduce some of the fiddly work learning the variable syntax for newcomers.

3. Breadth-first field-search

Another trickier feature would be a graph-wide, breadth-first, async search for when you know that there’s a field “with a name or description like something", but you’re not sure where in the API it is, or how to navigate to it.

The explorer is the perfect interface to allow quick searching for matching fields - and once you’ve found them, click on the desired field to select it, and have the entire ancestor chain automatically added as well! This would speed up both new comers searching through an API as well as so many daily tasks for experienced GraphQL developers.

Try it out!

You can try out the live version to query data from APIs like Stripe, Spotify, npm, GitHub, and more in OneGraph with an account, or with our public OneGraphiQL instance. There’s also an example repo that shows how to incorporate OneGraph’s GraphiQL explorer in your own GraphiQL instance.

Upgrading from the previous version

For users already on the old version, simply swapping the version number in your package.json for "graphiql-explorer": "^0.4.2" should bring many of the new features listed above. Some of the optional features, like running a query from inside the explorer or jump-to-definition, will require a bit more code, but it should be copy/paste-able directly from the example.

Special thanks

Many thanks to Alexey Rodionov who’s been helping out with mockups and idea suggestions for the explorer.

Thanks to Juho Vepsäläinen, Stepan Parunashvili, and Benjie for reviewing this post and an early version of the new release and offering great suggestions for improvement.

{"source":"blog","publishedDate":1559199600000,"url":"https://www.onegraph.com/blog/2019/05/30/GraphiQL_Explorer_2_0_A_Power_User_Release.html"}