Getting Started with GitHub's GraphQL API

June 12, 2018 0 Comments

Getting Started with GitHub's GraphQL API



  Follow on Twitter   Follow on GitHub

sponsor-logo This month, all my articles are sponsored by TRUMPF Laser GmbH. The german company I worked with is using a sophisticated React with GraphQL and .NET tech stack in production to bring highly configurable laser device user interfaces to their clients all over the world. These web applications are running in embedded systems as web application, but also as native applications on various devices. Find out more about career options in Berlin and in Schramberg.
github graphql API apollo react

I am writing a React GraphQL book which I intend to release the next months. If you are interested in following me on this journey or grabbing a copy of the book as one of its first readers, you can opt-in for receiving updates about it. Feel encouraged to leave me any feedback for improving the content. You can even contribute to it by editing this article on GitHub. After all, I want to produce a high quality book which should enable people to learn about GraphQL in React similar to The Road to learn React.

Often it is easier to learn something new by learning it step by step. When you start learning about GraphQL in JavaScript, you can dive into the client-side and server-side world at the same time. However, this might not be the best approach of learning about GraphQL, because now you have to deal with two environments instead of one. These are already two steps and not one. So the step by step mentality wouldn’t apply anymore. That’s why I encourage GraphQL newcomers to start with the client-side by consuming a third-party GraphQL API before diving into the server-side of using GraphQL.

GitHub is one of the major adopters of GraphQL who managed to release a public GraphQL API (official documentation). Their API is quite popular among developers to learn about GraphQL, because most developers are familiar with their platform. In the following, I want to give you everything you need to get started with GitHub’s GraphQL API for learning GraphQL in JavaScript. Maybe not all of the following sections are applicable to you, because you may already have an active GitHub account and you might be already set up for these topics.

If you don’t have an account on GitHub yet, you can follow this guide to sign up on GitHub, to get to know what GitHub is all about, and optionally to learn about a few essential git commands for the command line. After all, you might want to share your projects with others on GitHub which is a neat way to showcase your portfolio as a developer to hiring companies or clients of yours.

When interacting with GitHub’s GraphQL API, it would be great create some data for your own account on the platform in order to read/write from/to this data when using their API. Firstly, you can complete your GitHub profile by providing additional information about yourself. So if you read data about your GitHub account later by using their API, you should be able to see information such as your username or your avatar’s URL. The data you are going to provide or create here is available via GitHub’s GraphQL API later.

GitHub Repositories

Secondly, you can create repositories on GitHub. You may wonder what’s a repository? “A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private.” The quote is taken from GitHub’s glossary which helps you to get to know GitHub’s terms (e.g. repository, issue, clone, fork, push). Basically a repository is the place for your application’s source code to share it with others. If you don’t have any repositories on GitHub yet, I encourage you to put a few of your project’s (source code) into repositories by pushing them to GitHub. Later you can access those repositories with GitHub’s GraphQL API.

If you don’t have any projects for uploading them as your repositories, you can also fork repositories from other GitHub users to continue working on them. After you have forked a repository, it is available in your list of repositories. It is basically a clone of the original repository where you can add your own changes. That’s how open source works after all. There are many public repositories on GitHub which can be cloned to your local machine or forked to your list of repositories in order to contribute to them. For instance, when you visit my GitHub profile, you can see all my public repositories. You can navigate to a few of those repositories and fork them. Then you have those repositories accessible in your GitHub account which are available via GitHub’s GraphQL API in your account later on.

Working with paginated Data

Often you will request a list of repositories when using GitHub’s GraphQL API. Thus it is valuable to have more than one repository listed in your GitHub account, because later you may work with a mechanism called pagination. Pagination was invented to work with large lists of items. Imagine you would have more than 100 repositories in your GitHub account, but your UI only shows 10 of those repositories. It would be a bad idea to transfer the whole list across the wire when performing a network request because only a subset of it is needed. That’s where pagination comes into play. Different pagination mechanisms allow you to request only a subset (page) of your list. For instance, these can be the first 10 of your 100 repositories. When you are using pagination later with GitHub’s GraphQL API, make sure that you adjust the numbers to your own needs. If you have 3 repositories in your GitHub account, it makes sense to request only 2 repositories as your first page, and then again 2 more repositories (which would lead only to 1 more repository, because you haven’t any more repositories available) as your second page. Instead, if you would request all 3 repositories as your first page, you wouldn’t have any repositories left to request another page of repositories. Then it becomes hard to see the pagination feature in action. So make sure to adjust the numbers (e.g. limit, offset) to your personal requirements (e.g. available repositories of your GitHub account or available repositories of a GitHub organization).

Issues and Pull Requests

Once you dive deeper into GitHub’s GraphQL API and you start to request nested relationships (e.g. issues of repositories, pull requests of repositories), make sure that the repositories of your GitHub account or the GitHub organization, where you are requesting the repositories from, have a few issues or pull requests. Otherwise you may implement such a feature to show all issues in a repository, but you don’t see anything, because there are no issues in the first place. You may think it is a bug then but in reality there is just no data available. So in the end, it might be better to request active repositories from a GitHub organization, where you find issues and pull requests, rather than requesting repositories listed in your own GitHub account, where you don’t have any issues or pull requests.


  • read more about the different terms in GitHub’s glossary

    • what is a GitHub organization and GitHub user?

    • what are repositories, issues and pull requests?

    • what are GitHub repository stars and GitHub repository watchers?

In order to use GitHub’s GraphQL API, you need to generate a personal access token on their website. The access token makes sure that you can be authorized as a user who interacts with their data. Basically, it allows you to read and write data in your name. You can follow their step by step instructions to obtain the personal access token. While getting your token, make sure to check all the necessary scopes for it. You will need sufficient read and write permissions in order to implement a well-rounded feature set for a GitHub client.

react graphql github

Later the personal access token can be used to interact with GitHub’s GraphQL API. Basically it is your private key to access and manipulate GitHub’s data, so you shouldn’t share it with any third-parties.

There are two common ways to interact with the GitHub GraphQL API without writing any source code for it. Firstly, you can use GitHub’s GraphQL Explorer. You only need to sign up with your GitHub account in order to perform a query or mutation to their GraphQL API. That’s how you can make your initial experiences with GraphQL.

Secondly, you can use a more generic client in form of an application. GraphiQL is one of those clients to make GraphQL requests either as integration in your own application or as a standalone application. The former can be accomplished by setting up GraphiQL directly in your application. However, the latter may be more convenient for you by using GraphiQL as standalone application. It’s a lightweight shell around GraphiQL that can be easily installed on the command line or manually by downloading it.

Whereas GitHub’s GraphQL Explorer knows about your credentials, since you need to sign up using it, the GraphiQL application needs to know about your personal access token that you have created before. You can add the access token in your HTTP header for every request by opening up the headers configuration.

graphiql headers

In the next step, you need to add a new header with a name and value to your GraphiQL configuration. In order to communicate with GitHub’s GraphQL API, you need to fill in the header name with “Authorization” and the header value with “bearer [your personal access token]“. Afterward, save this new header for your GraphiQL application. Finally, you are ready to make requests to GitHub’s GraphQL API with your GraphiQL application.

graphiql authorization

Last but not least, in case you end up using your own GraphiQL application, you need to provide the GraphQL endpoint for GitHub’s GraphQL API: In case of GitHub’s GraphQL API, you are going to use the POST HTTP method for GraphQL queries and mutations. After all, you have to transfer the body of data as payload to your GraphQL endpoint.

In conclusion, the last paragraphs have provided you with two ways to interact with the GitHub GraphQL API. Whereas the GitHub’s GraphQL Explorer can only be used for GitHub’s API, GraphiQL, integrated in your application or as standalone application, can be used for any GraphQL API. As you might have noticed, the GitHub GraphQL Explorer is nothing else than a hosted standalone GraphiQL application, but it is tailored to only use GitHub’s GraphQL API.

After you went through these instructions that showed you how to set up GitHub in order to use their GraphQL API to learn about GraphQL itself, you should be ready to implement your first GraphQL client application with it.

Build a Hacker News App along the way. No setup configuration. No tooling. No Redux. Plain React in 190+ pages of learning material. Learn React like 28.000+ readers.

Get the Book

Tag cloud