There are many reasons why my team at Hootsuite has adopted GraphQL. The client has control over the granularity of the data transferred by cherry-picking fields and objects that it explicitly wants from the server. With this, mobile teams can use the same APIs as web without worrying about payload size.
However, GraphQL is not a simple replacement for REST or other forms of designing web services. This post will not attempt to declare GraphQL as a winner because it really depends on what your API needs to do. While using GraphQL has been proven suitable for my team, it seems that some of the unique benefits of its use have been lost in conversation. Another huge plus is that if your server speaks GraphQL, you can use GraphiQL. GraphiQL is an in-browser IDE for exploring GraphQL schemas where you can test queries and easily view the data being returned from the server. Check out this repo and live demo.
I almost titled this post “REST-in-peace to REST” but decided against it because GraphQL has only been adopted by a small portion of developers at Hootsuite. For now, I’ll give it a REST. If you’ve never heard of GraphQL, check it out.
To use any RESTful web service, you have to read the documentation to understand its uses and limitations. With GraphiQL, you’re provided with schema definitions from your GraphQL server and can explore what options are available without relying on your developers to make the API super descriptive.
GraphiQL is backed with:
- Automatic query completion
- Syntax highlighting
- Debugging as-you-type with suggestions of fields, arguments, types, etc.
Focused on the semantics of the data, you can clearly see if you’re sending the wrong argument types or fields. As soon as any changes are available in the GraphQL schema, you’ll see it in the GraphiQL browser.
On the right side of the IDE, GraphiQL supports a documentation explorer. Developers can easily explore the possible queries, mutations, types and their required and optional fields. The example below shows options of what we can query for. Conveniently, we can see the arguments that can be passed in and the return type of the query.
Note that all the arguments in the queries above are optional; required arguments are denoted with an exclamation, like below:
Another great feature is that the documentation panel will automatically remove any fields marked as deprecated by the GraphQL schema.
GraphiQL has a Query Variables panel at the bottom of the IDE that allows you to organize your inputs by passing JSON formatted variables instead of inline arguments into a query.
The setup can look something like this:
Query with In-line arguments:
Query with variables:
Quite often we find ourselves needing to write repetitive code in a query.
GraphiQL allows you to extract reusable structures called fragments. This allows us to combine multiple fragments into a single data fetch without having to write a complicated and messy query.
With a type system, we can see whether a query is valid or not before even running it.
For example, whenever you query a field and it returns data that isn’t a scalar, you must specify what data we want to get back from that field. When executing the query, GraphiQL will automatically suggest data you might want from the queried field.
GraphiQL automatically fills in the innermost field filmConnection by querying for the Id field under edges -> node.
GraphiQL comes with a nicely formatted JSON viewer so you can inspect query and mutation results. The structure of the results mirrors the original query requested by the client. This is because of how each field is resolved, starting from the leaf fields of the query and all the way back up to the original field of the root type. The resulting JSON maps the field name as the key and the resolved value as the value.
If the query is unsuccessful, GraphiQL highlights real-time errors.
If you decide to adopt GraphQL, GraphiQL is an indispensable tool. Allowing the client to choose what data it wants seems logical, and from what I’ve seen at Hootsuite, really drives the team to be more full stack. Having only a back-end developer implement the GraphQL server is complicated if you don’t know what each field is meant for. With shared documentation and visibility on every API update through GraphiQL, front and back-end developer teams can better negotiate and iterate to implement a GraphQL server that is clean and efficient.
Beriwan is a Software Developer Co-op on the Engagement team at Hootsuite. She is currently studying Computer Science and Creative Writing at the University of British Columbia.