Exploring GitHub with GraphQL

GraphQL + GitHub

While I was working on the project https://github.com/VietFOSS/vn-foss/ to collect information about open source projects contributed to by Vietnamese, I stumbled upon a gem from GitHub: GraphQL for querying its data. No more troublesome REST and I can query data with ease to eliminate intensive data entry work. Below are the steps to get started with GitHub GraphQL.

Play with GitHub GraphQL Playground

First you need to familiarise yourself with GitHub GraphQL schema and API, make some queries and convince yourself it’s the way to go. Unlike REST, GraphQL provides type-safe schema and you have only 2 modes: Query and Mutation. No more complicated HTTP verbs and mistakes over field names or field types! REST forces you to accept the output hierarchy and fields without change, but GraphQL allows you to specify what fields and how your output will look like.

Access it here: https://developer.github.com/v4/explorer/

I give you one simple query that I crafted to help you kickstart:

{
user(login: "vietlq") {
avatarUrl (size: 256)
bio
email
websiteUrl
company
location
}

Create Your GitHub Personal Access Token

Enough playing in the playground. Now we are after real applications that run on servers.

Open: https://github.com/settings/tokens

Don’t be fancy, give the token a meaningful name. The official documentation mandates that you need the following permissions (I reordered for simplicity):

repo
repo:status
repo_deployment
public_repo
admin
read:org
read:public_key
read:repo_hook
read:gpg_key
user

NOTE: Remember to store the token safety. GitHub will never show you the token again, so use 1Password or the likes to store.

Use the GitHub Personal Access Token

The first order of business: Never ever store passwords, credentials, tokens in the Git/SVN/public space!

You can export the value to the environment using your .bashrc or .bash_profile:

export GH_PERSONAL_TOKEN=abcdef

Once the environment has your token, you can use the token in 2 ways:

curl -v -u username:${GH_PERSONAL_TOKEN} https://api.github.com/user

or

curl -v -H "Authorization: token ${GH_PERSONAL_TOKEN}" https://api.github.com/user

Query GitHub GraphQL

In the previous part we learned how to use the GitHub Personal Access Token to make queries. To make calls to the GraphQL, we will use the end-point:

https://api.github.com/graphql

To retrieve GraphQL schema for GitHub, you need to send a GET request:

curl -u vietlq:${GH_PERSONAL_TOKEN} https://api.github.com/graphql

I’d advise you to use Postman for such purpose or use Python to retrieve the schema and then prettify it.

To make Query/Mutation, you will need a POST request. In this post we will make Query requests only:

curl -v -H "Authorization: bearer ${GH_PERSONAL_TOKEN}" -X POST -d " \
{ \
\"query\": \"query { viewer { login }}\" \
} \
" https://api.github.com/graphql

You should expect the response (replace YOUR_GITHUB_ID with your GitHub ID):

{"data":{"viewer":{"login":"YOUR_GITHUB_ID"}}}

If you read carefully, you will notice raw data expected is a JSON with the key query that encompasses the actual GraphQL query:

query {
viewer {
login
}
}

To avoid the pain of typing to the command line, let’s summon Python:

See, no private credentials exposed and you will get output like this:

{"data":{"user":{"avatarUrl":"https://avatars1.githubusercontent.com/u/197199?v=4&s=256","bio":"","email":"vietlq85@gmail.com","websiteUrl":"https://simpleit.us","company":"Dev Viet Ra Khơi","location":"United Kingdom"}}}

Now you are ready to make Query or Mutation calls to GitHub GraphQL and do whatever you wish.

Check the repo for code: https://github.com/VietFOSS/vn-foss

Remember to subscribe for more interesting articles from Code2Pro:

References

Like what you read? Give LE QUOC VIET a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.