Solving GraphQL's Onboarding Problem, Part 1

It's our first post of the year, and we’re opening with a new year's gift! We're open-sourcing our new GraphiQL explorer, which is the best way to explore any API today.

GraphQL: A nascent and growing technology and ecosystem

But first, let's talk a bit about GraphQL: it’s a production-ready query language that allows clients to declaratively specify the data they need in a way that best fits their product needs. The first stable release was in October 2016, which at two years old is pretty young for this kind of tech. Its popularity has grown rapidly and a strong ecosystem has started to take root, with services like Gatsby , Hasura , AWS AppSync , and of course, OneGraph.

We see a lot of newcomers to GraphQL at OneGraph. Many of them aren't aware that OneGraph is powered by GraphQL--they come to OneGraph looking for easy and consistent access to the services that power their business. Services like Gmail, Intercom, Twilio, Slack, etc. Given GraphQL is still a novel technology, many of them will see it for the first time - and that means they're one of the lucky 10,000!

We’ve invested deeply into making the first experience for the lucky 10,000 really special, both for OneGraph users, and for the wider GraphQL ecosystem as well.

GraphQL’s on-boarding problem

There’s a ton of value in GraphQL, and we’re obviously huge fans.

We’re also in a unique position because we see so many newcomers to GraphQL, and we get to do a deep dive on the things that trip them up. The biggest initial show-stopper that we found surprising (especially as GraphQL experts) is the overwhelming nature of the GraphQL syntax. We’ve stood over the shoulder of our users as they see a GraphQL query the first time, and that’s given us a visceral empathy for the fear it can inspire in the beginning: the nested structures, the not-quite-JSON-object fields, the lack of familiar docs. There’s a learning curve that many experts don’t appreciate.

Not only do GraphQL users have to learn an entirely new way of thinking, but also the syntax to represent that new way of thinking - both at the same time! And to add to that, it’s possible to end up with queries that look right, but the server won’t be able to execute successfully.

It’s a challenge that anyone who’s used GraphQL for a while finds suspicious: “It’s so easy! The query is JSON without the values. You know JSON, this is even easier!”

But because we’re exposed to lots of new-comers to GraphQL, we knew we had to search hard to find a way to show beginners how easy it really is.

GraphiQL: An integrated GraphQL development environment

One of the great things about GraphQL is the wonderful tooling that’s grown up around it, like GraphiQL. It’s a GraphQL exploratory tool that’s great for building up and testing queries, seeing the types of each individual field, being able to search through a schema for a field name or type, and even read the docs inline. It’s a core component of OneGraph’s data explorer.

Most of the efforts in GraphQL tooling have focused on the intermediate-to-advanced cases, meaning we have a big opportunity to help newcomers to the ecosystem.

Specifically, can we build tooling that allows a new user to easily discover the connection between the data they want to get and the query they need to write?

Introducing the OneGraph GraphiQL Explorer

Try it out!

Why we built the Explorer

OneGraph's GraphiQL explorer is a way to explore and build GraphQL queries, and can be included in any GraphiQL instance as a simple React component.

We built the explorer with a user story in mind:

Betty is full-stack developer who’s seen a few snippets of GraphQL, but has never written a query herself, and isn’t sure learning the syntax will be worth it. She’s been put in charge of building an internal dashboard system to get an overview on customer activity across several different services like Zendesk, Intercom, and Salesforce.

Let’s make Betty’s day special! We want her to first reach her goal, and along the way, become comfortable with GraphQL.

She’s not familiar with GraphQL syntax, so instead, let’s present her with a graphical representation of the data she’s looking for instead. We display the schema in a tree, almost like a file explorer, where she can check the fields she wants:

Now each possibility is presented neatly for Betty to choose. And as she selects each field, we build the corresponding GraphQL query for her:

Betty doesn’t have to be deeply familiar with GraphQL semantics or syntax now - we’ve pushed that bit of learning further down the road. More immediate wins for Betty means she can accomplish her goal faster, and see the concrete wins for GraphQL.

We can take it even further! When you or your company are embedding the explorer in your GraphiQL instance for your users, another challenge they'll face are cases where a query is syntactically valid, but semantically invalid.

Take a case we've seen many new users trip over, for example:

query {
    gitHub {
      user(login: "sgrove") {
        repositories {
          nodes {
            name
          }
        }
      }
    }
  }

It's obvious that the user is trying to get a list of repositories and their names, but they'll get an error back:

{
      "data": {
        "gitHub": null
      },
      "errors": [
        {
          "message": "Error from GitHub: You must provide a `first` or `last` value to properly paginate the `repositories` connection.",
          "path": [
            "gitHub"
          ]
        }
      ]
    }

This is because while all of the arguments for repositories are optional, the user must provide some arguments. This breaks the flow of a user building up a query, and really confuses new users.

So now a company embeds the explorer into their GraphiQL instance, they can optionally provide default arguments for cases where selecting a field would lead to these bad states. Simply specify additional arguments to fill in automatically when an ObjectType.fieldName is expanded, so that for example the same actions as before would lead to this query instead:

query {
    gitHub {
      user(login: "sgrove") {
        repositories(
          orderBy: { direction: DESC, field: CREATED_AT }
          first: 10
        ) {
          nodes {
            name
          }
        }
      }
    }
  }

Notice that first has been automatically selected and populated with a value of 10 , along with natural sorting options. This is a manual decision by us, the authors of the API, because we expect that while last: 10 is also a valid argument, first is more likely what users will be looking for. This allows for a longer unbroken chain of success as our users explore OneGraph.

For novices and gurus alike

While we initially targeted the explorer at newcomers, it’s even become the preferred way of exploring and building up queries for our customers who are experienced GraphQL developers! New and experienced alike get new super powers to use at their companies and on their personal projects, thanks to the explorer.

Technical details

The explorer is written in JavaScript with Flow typing to make it fit in as much as possible with GraphiQL's codebase. Because of the introspectable nature of GraphQL (where there's a standard way for a client to ask a server about details on its API), we're able to get a list of all of the fields under the query , mutation , and subscription objects. Not only that, but we can intelligently render argument input fields like enums, explore intermediate concepts like interfaces and unions, and even bring in field and argument-level documentation on hover. Check out the source if you’re curious about the implementation and an example of how to use it in your own GraphiQL instance.

OneGraph’s Open Source Contribution

Today we’re providing our GraphiQL Explorer to the wider community as an open source contribution. I'm really proud of what the we've been able to build, and even more excited to think we contribute in some small way to thousands of others learning and enjoying GraphQL. Expect to see it soon in your favorite projects like Gatsby, Postgraphile, and more!

Take a look at the GitHub repository for the explorer itself, and check out our ready-to-go example to see how to use it in your own GraphiQL instance!

A special thanks

The seed of the idea originally came from Steve Hazel over tea in a cafe while he gave us early feedback on OneGraph. It took a while to work out the implementation, but we’re very thankful for him sharing this insight.

Footnotes