I'm working on a series of a posts about GraphQL in order to get more familiar with what it is and what it's capabilities are. I hope you find these useful too!
- Part 1: What is GraphQL and how does it differ from REST?
- Part 2: Using the GraphiQL IDE to access a GraphQL API
- Next ➡ Part 3: Using GraphQL for .NET to access a GraphQL API
In the last post, I just wanted to understand what GraphQL is, and the justification for using it. What I learned is that it's about flexibility and efficiency; getting exactly what you need, in the format you need it. Now I want to look at an actual implementation.
Unfortunately, Facebook spent years developing an amazing tool (that's right, FB designed GraphQL), but have screwed up so badly and so often that anything they do has a stain on it. Fortunately, GraphQL is open-sourced and there's another tech giant that implemented it too, so we'll see how they did it.
When GitHub began moving to a new version of their API several years ago, they migrated from REST to GraphQL. Their reasoning is very similar to what I've read elsewhere and experienced myself.
Our responses were bloated and filled with all sorts of
*_urlhints in the JSON responses to help people continue to navigate through the API to get what they needed. Despite all the information we provided, we heard from integrators that our REST API also wasn’t very flexible. It sometimes required two or three separate calls to assemble a complete view of a resource. It seemed like our responses simultaneously sent too much data and didn’t include data that consumers needed.
One of the tools available with GraphQL is GraphiQL, which allows users of your API to design queries right in the browser and see immediate results. This is a tremendous time-saver!
With REST, I've always used Postman to manage my queries without having to have a fullblown app in place from the get-go, but it still involves trial and error. You have to read the API's docs, figure out what you want to call and how, get the result and inspect it, make adjustments, make more calls to other endpoints, blahdee blah blah blah. Occasionally, an API provider produces their own "API Explorer" of sorts, which lets you try calls right in the browser, but that cannot be easy to develop and maintain...
GraphiQL is a ready-to-go "API Explorer". It integrates API docs right into the experience with "typeaheads" (similar to intellisense in Visual Studio), which helps you figure out what to query and then shows you the results. Let's try out GitHub's API explorer.
- Allow it to access your GitHub account... even though it is GitHub. 🤨
- Click the "Execute Query" triangle in the upper-left to run the default query... info about you!
- Click the "Docs" button on the right side to view the API documentation. Note the two root types - query and mutation. A query is similar to a REST
GET, while mutation is similar to
DELETE. Stick with query for now.
- As you drill down, you can see objects to query, parameters to restrict your queries, and other child objects. It's like you're getting to browse their database!
Here's a few queries I tried running:
Once you've run a few queries, try out mutations. You've already granted access to everything in your account to the tool, so you can update (mutate) pretty much anything in your account. Here's a short screen capture of me doing two things:
- A query to get the ID associated with an open issue in one of my repos
- A mutation to add a few reactions to the issue
As with running the queries, having the documentation on the right side is great. I was able to drill down and see that
addReaction requires an
AddReactionInput type, which consists of three things - and only two are required (notice the
The only thing that seemed unintuitive to me was the requirement to have a body in the mutation, as if it's required to return something even though if you were doing a REST
POST you wouldn't care about anything except a return code of
I think the next thing I'd like to try is using one a tool like GraphQL for .NET to access the GitHub API from an application, instead of GraphiQL. 😎