GraphiQL: GraphQL’s Killer App
Maybe you haven’t heard of GraphQL. It’s a query language for front-end engineers to retrieve data from the back-end. It might be helpful to think of GraphQL as an alternative to REST or JSON-API.
So why does GraphQL matter? Why ditch known quantities like REST, SOAP, or whatever homegrown system you’re using?
The specification’s Overview has some good points, but let me appeal to you in a different way: if you use GraphQL, you can use GraphiQL. And GraphiQL is a delight.
If you want to play around with GraphiQL (note the i, “graphical”) right now, take it for a spin on GraphQLHub.
Pre-GraphiQL
Exploring and debugging APIs isn’t very fun. On one end of the spectrum we have applications like Paw and HTTP Client, and on the other end we have cURL and wget. If you’re lucky you can use specialized tools like Sense.
These reduce boilerplate and improve portability, but they are ignorant to the semantics of your data. If you send the wrong type of argument, or want to explore what options are available, you have to rely on the API to be descriptive and helpful — usually the last thing on the team’s TODO list.
But if your server speaks GraphQL, you can just use GraphiQL.
Docs
Documentation is a first-class citizen of GraphQL, and GraphiQL leverages it. The right-hand pane exists for you to explore the possible queries, mutations, fields, their types, if they’re required, the works. Even if your server doesn’t implement human-composed descriptions, you will always be able to explore the graph of possibilities.
And just as GraphQL supports deprecation, so does GraphiQL — in a sense. GraphiQL will automatically remove deprecated fields from the documentation. No more discovering fantastic endpoints that disappear a month later.
Debugging
You don’t even have to read the documentation to discover your API. GraphiQL supports debugging as-you-type, giving hints and pointing out errors.
If you’re working on a GraphQL query with variables, you can use the query variables pane to store your current work.
JSON Viewer
GraphQL responses don’t have to be JSON, but it’s preferred. GraphiQL comes with a JSON viewer with all the niceties you’d expect: code folding, automatic indentation, copy support, and read-only so you won’t accidentally delete or edit.
Sharing
“Virality” is built into GraphiQL. When you edit a query, the URL updates immediately. Everything is preserved — whitespace, comments, even invalid queries.
It’s intuitive to share with your colleagues or publicly — find something interesting? Send the URL. Slower-than-expected or buggy query? Add a link to the bug report.
For all these reasons, I’m moving more of my APIs to GraphQL — just so I can use GraphiQL. Tucci’s API is one example.
I’m excited for even more tooling built with GraphQL’s introspection features. I used to believe that Relay was the killer app for GraphQL, but now I think that GraphiQL is the Real McCoy.
