GitHub GraphQL (API)

GitHub’s REST API was perfect. Now THIS is more perfect.

Overview

GitHub’s GraphQL Endpoint
Technologies to Access
GitHub Documentation
GitHub Auth Token
Custom Graphene program
- GraphQL
- Flask app
Programmatic access
More on API Microservices
More about Git & GitHub

This article covers working with GitHub’s GraphQL by manually issuing single requests and by programming.

GitHub’s GraphQL Endpoint

GitHub provides a well-known GraphQL API end-point which accepts a lot of traffic for all operations:

https://api.github.com/graphql

GitHub was among the first to adopt GraphQL’s leading-edge API techniques, so their APIs are referenced as an example industry-standard we would do well to emulate:

HATEOS-based REST API, (my BFF last year) such as PowerShellforGitHub
Facebook’s GraphQL (described by my article on GraphQL)

I first looked at GitHub’s GraphQL API in 2016 during their ~~https://developer.github.com/early-access/graphql/~~ which included the ~~https://developer.github.com/early-access/graphql/explorer/~~

Technologies to Access

As with any API, there are several ways you can there make calls:

Without installing anything: on a Terminal CLI crafting curl commands
Installing a client programs: Insomnia on the Mac or Windows.

Read: https://insomnia.rest/blog/oauth2-github-api
Alternatively, install a (Chrome or Mozilla Firefox) browser extension: Postman, Advanced REST Client, Talend API Tester.
Custom programs.
Installing a programming environment: Python, NodeJs, Ruby, etc.
TODO: Reference an OpenAPI (Swagger) spec file.

GitHub Documentation

GitHub’s Developer Guide on GraphQL is at:

https://developer.github.com/v3/guides/getting-started

Others:
- https://developer.github.com/enterprise/2.20/
- https://developer.github.com/enterprise/2.20/apps/
  Building apps
Click https://docs.github.com/en

Notice there is a REST API and GraphQL API.
Click “GraphQL API” at https://docs.github.com/en/graphql

“to create precise and flexible queries for the data you need to integrate with GitHub.”
Get a GitHub account if you don’t already have one.

GitHub’s guides provide sample API calls using the curl command-line utility.

GitHub Auth Token

Even working on public repos, unauthenticated clients can make only 60 requests per hour and see limited informaiton unless you get an authentication token to make a call like this:
```
curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
 https://api.github.com/user/repos
```
-H specifies the token in the HTTP header (which is more secure than in Query parameters).
Click your avatar image at the upper-right corner to be at:

https://github.com/settings/profile
Click “Developer settings” in the left menu to be at:

https://github.com/settings/developers
Click “Personal access tokens”.

VIDEO and this blog explains the steps for generating a PAT for Insomnia to use as a bearer authentication token. It references this GitHub doc.

PROTIP: Remember that a PAT (Personal Access Token) is the same as your account password which grants full access to all your repositories within your account.
Check “Enterprise billing”, then “Save”
Click the clipboard icon to capture the key to your Clipboard.
Paste the key text in the Insomnia app.

OAuth App

An “OAuth App” (such as Insomnia) acts as a GitHub user.

A “GitHub App” uses its own identity installed on an organization (granted by an organization administrator).
Click “OAuth Apps” to register a new OAuth GitHub app at:

https://github.com/settings/applications/new

READ: https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps
Navigate to the Settings page of the repo you want to use APIs on.

NOTE: You need to be an owner or Administrator to see “Settings” tab.

Deploy keys limits access to a specific repository in your account using SSH.
Register a new OAuth application

https://github.com/settings/applications/new

See https://docs.github.com/en/rest/guides/basics-of-authentication

https://docs.github.com/en/rest/reference/repos#create-a-repository-for-the-authenticated-user
In the Deploy keys menu, click “Add deploy key”.
Be in your home user folder, which is never pushed to any public GitHub. Here is where you can keep files containing secrets.

PROTIP: Create a file named “.pygithub-secrets.env” containing your information instead of mine:

MY_GIT_USER_NAME="JohnDoe"
MY_GIT_USER_EMAIL="johndoe@gmail.com"
MY_GITHUB_USER_NAME="JohnDoe"
MY_GITHUB_PASSWORD="Pa$$w0rdisnotsecure"
MY_GITHUB_TOKEN="23441234f13b1134c36667a"

If you’re using GitHub Enterprise behind the Okta identity provider (IdP) for SSO (Single Sign On), you will need to be given access that instance an probably have to install a VPN client as well.

https://help.github.com/en/github/authenticating-to-github/about-authentication-with-saml-single-sign-on
READ GitHub’s REST API documentation at:

https://help.github.com/en/github/setting-up-and-managing-organizations-and-teams/about-identity-and-access-management-with-saml-single-sign-on

https://medium.com/swlh/introduction-to-graphql-with-github-api-64ee8bb11630

Install client program Insomnia
PROTIP: Instead of downloading from https://insomnia.rest/download, install Insomina into the ~/Applications folder on your Mac, using Homebrew:
```
brew install --cask insomina
```
Alternately, on Windows within Git Bash run as Administrator (with elevated privileges), use Chocolatey:
```
choco install -y insomina-rest-api-client
```
NOTE: Insomnia is built using GitHub’s Electron, which enables coding of JavaScript to generate programs running on macOS and Windows. Insomnia is MIT open-sourced at https://github.com/Kong/insomnia

Swagger can be generated from API definitions in Insomnia using Swaggymnia

v3 GraphQL
There is a set of calls which can be loaded into Insomnia from:

https://github.com/swinton/github-rest-apis-for-insomnia

That is v3 of GitHub’s API, which made individual REST calls.

“Imported Worspaces” categories, alphabetically:
- activity
- apps
- checks
- codes-of-conduct
- emojis
- gists
- git
- gitignore
- interactions
- issues
- licenses
- markdown
- meta
- migrations
- oauth-authorizations
- orgs
- projects
- pulls
- rate-limit
- reactions
- repos
- scim
- search
- teams
- users
PROTIP: GraphQL is V4 of GitHub’s API. GraphQL calls can request any of the above categories of data in a single call. Conversion to GraphQL saved Github, Facebook, and others tremendously reduced traffic, bandwidth, and server processing load.

v4 GraphQL

https://support.insomnia.rest/article/176-graphql-queries says Insomnia provides auto-completion and linting of GraphQL queries.

BLOG: https://medium.com/swlh/introduction-to-graphql-with-github-api-64ee8bb11630

Custom Graphene program

GraphQL

https://github.com/graphql-python/gql is a GraphQL client for Python. Plays nicely with graphene, graphql-core, graphql-js and any other GraphQL implementation compatible with the spec.

Flask app

The app provides a UI to GitHub API calls made by the model_gh.py program.

Pavel Prudký (from Prague) shared his Python Flask mvc app to list/manage GitHub branches and files on his GitHub:

Programmatic access

Programs program enable automated preparation of calls and handling of results (looping through a list, saving to a database, etc.).

People have open-sourced libraries of code so you don’t have to “reinvent the wheel”.

Ruby

Internally, GitHub was orginally written in Ruby. Thus: https://developer.github.com/enterprise/2.20/apps/quickstart-guides/using-the-github-api-in-your-app/

Javascript

GitHub’s ProBot is written in TypeScript language for NodeJs, is a framework to extend the functionality of GitHub, such as these, listed by number of stars.

Python

Visit https://github.com/PyGithub/PyGithub, which is now being maintained by Steve Kowalik, who works at SUSE in Syndey, Australia.
Docs on PyGitHub shows sample Python code. I modified it (with added notes) in my repo at:

https://github.com/wilsonmar/python-samples/blob/master/pygithub-hello.py

The above repo is private. Ask me about making you a collaborator.

My version of the code references system variables so that secrets are not stored in code on public GitHub.
Looking at the code, the program looks for that default file name holding secrets if there is no override file specified with the program execution call. If neither is found, the program falls back to reading individual environment variables.
```
pygithub.sh
```
When executed, the response from pygithub-hello.py is simply:

pip install pygithub is based on code:
Make sample Python calls

The canonical websit on GraphQL has sample Python code: https://graphql.org/code/#python

Want your own GraphQL server?

You may want a custom (proxy) server responding to requests from your company’s apps, so they don’t all have to make calls to GitHub.

This may be because you don’t want to grant every program access to all information, which is what GitHub currently does. GitHub doesn’t limit the content of data accessed by a token, only categories of their services.

A custom server would enable you to respond any way you want. (But you also have to worry about providing enough capacity, unlike a SaaS offering like GitHub)

There are two major Python code library for implementing GraphQL servers:

The Graphene Python library takes a “code-first” approach:

https://docs.graphene-python.org/en/stable/quickstart

“Ariadne” using a SDL (Schema Definition Language) so less coding is needed.

https://ariadnegraphql.org/ describes https://github.com/mirumee/ariadne

More on API Microservices

This is one of a series:

More about Git & GitHub

This is one of a series on Git and GitHub:

Wilson Mar