GitHub GraphQL API Guide

Nowadays many companies use GraphQl API instead of traditional REST API. This is the case due to the fact that GraphQL offers the ability to define precisely the data you want - and only the data you want, which is a powerful advantage over traditional REST API endpoints. GitHub offers one of the great examples of a good GraphQL API.

Why GitHub started to support GraphQL specification? There are two main reasons:

  1. REST API wasn’t very flexible (it sometimes required two or three separate calls to assemble a complete view of a resource, moreover responses simultaneously sent too much data and didn’t include data that consumers needed).

  2. GitHub has an extremely detailed requirements for it’s API, which includes: an access for GitHub documentation in requests, pagination of resources, assurances of type-safety for user-supplied parameters etc.

GraphQL became a great solution for GitHub to manage the above mentioned tasks. With this API you can learn GraphQL technology in practice, you’ll be able to collect GitHub repository statistics and use this information in your projects.

This guide will cover the following topics:

  1. How to authenticate to the GitHub GraphQL API.

  2. How to run GitHub GraphQL API requests in API Tester, specifically:

  • Sending GraphQL queries in the request body;

  • Setting arguments;

  • Accessing the docs;

  • Using GraphQL variables;

  • Inline Fragments.

How to authenticate to the GitHub GraphQL API?

The GitHub GraphQL API has certain limitations in order to protect GitHub's servers against excessive or abusive calls. To make requests, you need to generate a personal access token. Detailed instructions on how to generate a token are available in the GitHub official documentation:

https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Note that getting an access token is compulsory in order to make any GitHub GraphQL requests!

Run GitHub GraphQL API queries in API Tester

API Tester has built-in support for GraphQL. So with the API Tester app on your mobile device you can:

  • send GraphQL queries in the request body,

  • use GraphQL variables,

  • use GraphQL content type headers,

  • browse GraphQL API Docs.

To get started with constructing you GraphQL request in API Tester:

  1. Launch API Tester and create a new request by tapping on the “Plus” icon.

  2. Select GraphQL method. The GraphQL request creation screen will open.

  3. The GraphQL API has a single endpoint, which remains constant no matter what operation you perform. Place GitHub GraphQL endpoint URL in the address field:

    https://api.github.com/graphql

  4. Open the Settings tab, select OAuth in the Auth section. Place your personal token in the Access Token field.

Now you can build the request body. Let's go to the Body tab and try to get an information about your login.

  1. Enter the following code as the request body and tap the “Send” request button.

    query { 
  viewer { 
    login
  }
}

Make sure to replace XXX with your own bearer token!

2. We received the response from the server which includes your login. Congratulations, you have generated your first GraphQL request in API Tester!

Setting arguments for GraphQL request

Now, let's try to set the argument for the request. As an argument, we use the "key : value" pair, where the value will be a certain login. Place this code as the request body to receive user’s avatar URL for a specified login: 

query {  
  user(login:\"Matthew3dg\") {  
     avatarUrl
  } 
}

Make sure to replace XXX with your own bearer token!

Tap the "Send" button and you will receive the following response:

Accessing the docs

The Docs tab allows you to browse documentation provided by API developers and to see exactly what arguments the server requires for a particular request. Let's go to the Docs tab and review the list of requests that can be sent to the server with their parameters.

We'll use the docs list form the previous request and find there a request with information about repositories sorted by their topics.

The screenshot above shows that the "name" argument of the "String!" type must be passed to the request to get the topic. Also, you can find a type details for this request and study them.

We can, as well, open documentation for a repository request, which will return an array of repositories with the topic specified in the argument. And now, we can form the following query:

query { 
  topic(name:"react"){
    repositories(first:10){
      edges{
        node{
          description
        }
      }
    }
  }
}

Make sure to replace XXX with your own bearer token!

Send this request and the response would be the following:

Let's try to send a similar request and get the total number of repositories with a given topic and also get a list of related topics. Paste this code into the Body tab:

query { 
  topic(name:"react"){
    repositories{totalCount}
    relatedTopics(first:10){
      name
    }
  }
}

Make sure to replace XXX with your own bearer token!

The response for this request would be:

Interesting statistics, isn't it? The value of the totalCount field is impressive! Such a number of repositories indicates the popularity of the React library.

Using GraphQL variables

Now let's form a request with using variables. To describe variables in the API Tester app, you should use a Variables tab.

Enter the code presented below in GraphQL Variables tab. As a "login" value you can place your personal data to make it more interesting to study GraphQL:

{
  "number_of_pull_requests": 3,
  "login":"Matthew3dg"
}

Now place the following code into the Body tab of request:

query($number_of_pull_requests:Int!, $login:String!) {  
  user(login:$login) {  
  pullRequests(first : $number_of_pull_requests ){ 
    edges { 
      node { 
        title 
        changedFiles 
      } 
    } 
  } 
  } 
}

Make sure to replace XXX with your own bearer token!

To add parameters in query you need to specify them in the Variables tab in a key-value format. Then you should place the name of the variables into the query part of the request body. The server will return the following response:

As a response we get an array of pull requests data with the topic and the number of modified files for each element.

Inline Fragments

Consider a more complex query with Inline Fragments. In this example, we will get an array of repositories with a "name" field for each, a list of commits with the date, and message for each commit. You can read more about Inline fragments in the GraphQL documentation:

https://graphql.org/learn/queries/#inline-fragments


Paste this code into the Body tab:

query {
  viewer {
    repositories(last: 5) {
      edges {
        node {
          name
          ... on Repository {
            defaultBranchRef {
              target {
                ... on Commit {
                  history(first: 10) {
                    edges {
                      node {
                        ... on Commit {
                          committedDate
                          message
                       }}}}}}}}}}}}}

Make sure to replace XXX with your own bearer token!

The requested data will be received in the response below. As you can see from the screenshot, response shows name of repository and committed date.

Let's try to get more detailed data, such as an array of tags of a certain repository. To do that,we will specify "name" and "owner" in the arguments for the repository request. Also, for the refs request, specify the "refPrefix" argument, which should start with "refs/". The request body will look like this:

{
  repository(name: "linguist", owner: "octocat") {
    refs(refPrefix: "refs/tags/",last: 5) {
      nodes {
        name
        target {
          oid
        }
      }
    }
  }
}

Make sure to replace XXX with your own bearer token!

The response for the request above will be following:

PreviousAPI Tester featuresNextGoogle Cloud APIs Guide

Last updated