Intro to GraphQL
Using Github's Public API to understand what GraphQL can offer:
To see what Github's REST API (v3) can provide we can go to the parent route (https://api.github.com/) which will list all of the possible routes we can use. For v4 we can login to use their explorer (https://developer.github.com/v4/explorer/).
We're going to use the mock account "Octocat" and its repository "Hello-World" to query for data.
To GET data of this repo, we can go to https://api.github.com/repos/octocat/Hello-World. As you can see we have a lot of info returned to us, but what if we only wanted the description of this? You can't unfortunately, you would need to request all of this "useless" info as well. This where GraphQL comes in the picture.
In the explorer use the following click the play button:
To the right, we will get only the description of the repo.
Already, we can see that GraphQL is a powerful way to selectively query for data we only need. So how did I write this query? GraphQL is a query language that is self-documenting. On the same bar as the play button, there is a "Docs" tab you can open that shows all of the possibilities using the Documentation Explorer. You can see the keyword "repository" is available.
Begin typing 're' within the query object to see a popup with repository as an option.
Right after it is typed or selected, you'll see an error informing you this needs brackets following this. Click it to open the Documentation Explorer to the right. Scroll down to see the various fields that are available. You'll see 'description' as an option. And since this example is of a simple string you can type the this as a field inside the brackets.
Alright, so far pretty simple. But what else can GraphQL do? What if we wanted bits of data from separate API responses?
Here's an example of that. Let's try to get the following in one request.
- The repository description.
- The title of a specific issue in the "Hello-World" repo. (We'll use issue
- The first 5 comments of the issue.
- And for each comment, get the comment author's username and the comment body text
If you wanted to do this using REST, you would need to make 3 separate requests to get these and with that would bring 3 times as much useless data.
However, with GraphQL it's possible with one request and given a response with zero useless data. Keeping what we had before, perform the previous steps to create this query below.
Note! What comes in parenthesis you will have to read in their Documentation Explorer to see what's possible. You can think of this as a kind of filter. The correct term for this is "Arguments"
You might notice for
comments to explore
IssueCommentConnection, from there you will see
IssueCommentEdge as its type and within this you will discover
node, this is where you'll stumble upon the
Take notice that
issue required an argument, but not comments. This is because it's asking us to be specific if we're going to use this. Where as with comments, we don't necessarily need to filter the first 5 and and ask for as many as we like!
Once you're ready, click play to see the results!