Get started with GitHub GraphQL API 👨‍🔬

#graphql #node #webdev #javascript

GraphQL APIs are since a few years more and more popular. The purpose of this tutorial is not to teach you the GraphQL concepts and techniques but to teach you how to query the GitHub GraphQL API.
I will use Node.js for the example, but you can achieve it with any programming language which allows you to perform HTTP request.

Setting up

First of all, you need to create a personal access token.

github > settings > developper settings > personnal access token > generate new token

Github will ask you a token description and the scope for your application, select what you need.

Now that we have our token, it's query time 🎯

Create Query

To test and create your queries, GitHub proposes a very powerful tool : GraphQL API Explorer.

For this example, I've created a very simple query to get my GitHub pinned repositories, which is not possible with the GitHub REST API.

query{
  repositoryOwner(login: "thomasaudo") {
    ... on User {
      pinnedRepositories(first: 6) {
        edges {
          node {
            name,
            description,
            url
          }
        }
      }
    }
  }
}

The documentation is really complete 📒

Query

To query the GitHub server, we will need to send a post request to the unique endpoint
Of course, we have to custom a little bit our request :

A parameter: the query
Bearer Authentication also known as token authentication: your personal access token ( in the header )

A CURL example from the GitHub official documentation :

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

I have created a really simple nodeJS example. To perform the query, I use the package 'axios'.

// Require axios to perform easy promise-based POST request
const axios = require('axios');
// Define constant
// Endpoint URL
const githubUrl = 'https://api.github.com/graphql'
// Your personal access token
const token = '7bacddc5d40dabfe6edca28b986a0247cfe3803b'
// The Authorization in the header of the request
const oauth = {Authorization: 'bearer ' + token}
// The GraphQL query, a string
const query = '{' +
                'repositoryOwner(login: "thomasaudo") { ' +
                  '... on User {' +
                    'pinnedRepositories(first: 6) {' +
                      'edges {' +
                        'node {' +
                          'name,' +
                          'description,' +
                          'url' +
                          '}' +
                        '}' +
                      '}' +
                    '}' +
                  '}' +
                '}'

// Post request, axios.post() return a Promise
axios.post(githubUrl, {query: query}, {headers: oauth})
  .then(function (response) {
    // On success, print the response
    console.log(response.data);
  })
  .catch(function (error) {
    On error, print the error
    console.log(error);
  });

Here we are!

I hope you have liked this post, my first one 🚀